Azure-devops-docs: Reference information on task.json is strangely sparse

[JamesMiera]

Though the effort is appreciated, the single paragraph "reference" information provides no actual information. One might as well have said, "The developers know how this works. I don't. Good luck scanning through the repo." The link itself shows obvious evidence that documentation stories, though vitally valuable to end users, are not much fun to write and should therefore be pushed to later sprints. Unfortunately, since the value lies within those customers' ability to actually write tasks, this page evades responsibility entirely.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 83f7acc5-1222-7216-571b-913fa63298e4
• Version Independent ID: 15b2e074-4a8d-9ac8-8aa8-56a0c11be534
• Content: Custom build/release task reference
• Content Source: docs/extend/develop/build-task-schema.md
• Product: devops
• GitHub Login: @elbatk
• Microsoft Alias: elbatk

[elbatk]

Hi @JamesMiera , what would you like to see different here?

[JamesMiera]

The documentation reads:

Custom build task JSON

When creating a custom build or release task with an extension, your extension will include a task.json file for each build or release task. This file describes the build or release task and is what the build system uses to render configuration options to the user and to know which scripts to execute at build time.

The build/release task SDK documentation is here.

The "here" provides no information on how to actually "describe the build or release task". Thus, I'd prefer to have at least a schema or some other reference that describes the fields in a task.json file. I'm currently learning by searching through existing custom task projects on GitHub, which forces me to falsely assume that those projects are accurately composing task.json files.

[zsmorris]

It seems like this issue has been ignored for quite some time:
https://github.com/Microsoft/vsts-task-lib/tree/master/docs

[vtbassmatt]

@JamesMiera @zsmorris you're right, the whole set of docs around publishing a pipelines task needs some love. I can't promise to fix it overnight but I'm putting this on my radar. (--the PM responsible for pipeline task engineering)

[vtbassmatt]

We've spent time improving the docs for creating a build task. I have one last change that's in PR right now, but the rest has deployed.

[zsmorris]

Good news @vtbassmatt ! Could you include a link(s) to updates? Looking at this repo, I'm not finding any changes (or the PR to which you've referred). Thanks.

[vtbassmatt]

The PRs are in our internal repo, unfortunately. The publishing of my last change should happen tonight; the previous changes edited this topic