Azure-devops-docs: The documentation could be a bit clearer

[lbrownell-gpsw]

There are disparities betwen the yaml illustration and the descriptions. Some are simply a matter of case and spaces, which I'm not listing, but others are arbitrarily different, and others are missing in one place or the other. And, one wonders, why not make them an exact match, so there is no ambiguity?

In these, the description title and it's probable matching key are shown:
Workspace or project path -> xcWorkspacePath
Xcode developer path -> xcodeDeveloperDir
Signing style -> signingOption: 'nosign' # Optional. Options: nosign, default, manual, auto
This one is a bit special: the description has multi-word phrases for each option, highlighted, as if those were
what one is to use; the yaml shows single terms. Which is it?
Create app package -> packageApp? In the yaml listing, this isn't commented-out, and no value shown.
Maybe optional, true if you want it?
Export arguments -> exportArgs
Destination type -> destinationTypeOption
Simulators -> destinationSimulators
Devices -> destinationDevices
Arguments -> args
Publish test results to Azure Pipelines/TFS -> publishJUnitResults

This is listed in the text description, but not shown in the yaml listing:
Output directory

These are in the yaml illustration, but not in the descriptions:
exportTeamId
provisioningProfileName
destinationPlatformOption
The pair Destination platform -> destinationPlatform exists, but no description of
destinationPlatformOption is given.

Thanks.

---

Document Details

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

• ID: 36460c87-c713-0930-461b-92da65e415e6
• Version Independent ID: 047d39f1-481b-c135-36e9-6cfc1cc92e99
• Content: Xcode build and release task - Azure Pipelines
• Content Source: docs/pipelines/tasks/build/xcode.md
• Product: devops
• Technology: devops-cicd
• GitHub Login: @DavidStaheli
• Microsoft Alias: dastahel

[msebolt]

@lbrownell-gpsw Thank you for the feedback!

You make some interesting points which I will forward on to the author.

Since there is nothing outwardly "wrong" with the documentation I will be closing the issue. Please comment below if you have any further suggestions.

FYI @davidstaheli

[lbrownell-gpsw]

Nothing wrong, you say. Pretty lax standards at MS these days; then again, it was a bit hard to read, due to how the form on the doc page ported it to a github issue.

So, let's try that again...

For these, the item on the left is the title in the description; on the right, what's shown in the yaml example.

Signing style -> signingOption: 'nosign' . # Optional. Options: nosign, default, manual, auto
Besides style vs. option, the description has multi-word phrases for each option, highlighted, as if those were what one is to use; the yaml shows single-word options. Which is it, single-word or multi-word?

Create app package -> packageApp
In the yaml listing, this isn't commented-out as are the rest of the items, and no value is shown...which is required, that's a key-value pair with no key. So that's illegal yaml.

These are in the yaml illustration, but not in the descriptions. Self-documenting I suppose, but why leave these out?

• exportTeamId
• provisioningProfileName

On this one:

• destinationPlatformOption
  The pair Destination platform -> destinationPlatform exists, but no description of
  destinationPlatformOption is given.

I haven't repeated the options where the description title does not match the actual yaml syntax, but differs in by adding spaces and changing capitalization. Humans should be able to deal with that, apparently.

[msebolt]

@lbrownell-gpsw Thank you for the clarification.

[MaxGuernseyIII]

I've been beating my head against the wall for days, trying to interpret the document. Opening up this comment is what made it make sense for me.

The signingOption is particularly counter-intuitive and its documentation is particularly misleading.

Can we please fix the issues so the next non-iOS developer trying to do an iOS build isn't led astray the way I was?

[cxwtool]

This issue hasn't been updated in more than 180 days, so we've closed it. If you feel the issue is still relevant and needs fixed, please reopen it and we'll take another look. We appreciate your feedback and apologize for any inconvenience.