Xamarin-macios: Updating error documentation generation/workflow

[spouliot]

Here errors means both errors and warnings.

Current Situation

• We have a good workflow that ensure any new error gets documented in the same PR. However it's not clear how contributors can participate in this workflow;

• The number of errors has grown a lot over the years. Just loading the single error document on a slow internet connection take time. Also the position in the document means you can see more than one error;

• We have to duplicate many MTxxxx (Xamarin.iOS) and Mmxxxx (Xamarin.Mac) documentation and keeping them in sync (with future changes) is a manual process;

• Making global changes, e.g. bugzilla to GitHub issues, requires a lot of changes;

Ideal Situation

Use a better format (but avoid NIH syndrome), e.g. align our error documentation format with csc, e.g. https://docs.microsoft.com/en-us/dotnet/csharp/misc/cs0841

This means:

• One index page (the current doc pages for mtouch and mmp) with links to all errors pages. That makes existing IDE still point to the correct information;

• One error per web page, including the description, how to correct the error, example(s) (if applicable). This gives faster download and a clearer view;

• Add instructions to use GitHub Edit so people can propose changes, i.e. https://help.github.com/articles/editing-files-in-your-repository/

Also

• Avoid duplication of MTxxxx (Xamarin.iOS) and MMxxxx (Xamarin.Mac). Write the documentation once and have it copied to both tools;

Required Steps

• Add a markdown template for new errors in docs/website/;

• Define a few _macros_ that inject blocks, e.g. %PLEASE_FILE_GITHUB_ISSUE% and %HOW_TO_EDIT_IN_GITHUB%, so we can do global changes easily;

• Update the simple copy to documentation repo to process the files first, i.e. apply macros, create the index pages...

• Add a new issue template in GitHub that's specific for people reporting the build error/warning;

• Add a new issue template in GitHub that's specific for people reporting comments on the error/warning documentation;

• Modify the IDE to load the specific page for the error (not the anchor on the single page). Current versions of the IDE will point to the index page (so one click away). People updating to the next stable milestone won't even notice;

[chamons]

I like the idea. Keeping MM and MT errors in sync, across branches without overlap is not fun and easy to screw up.

Question - Do we know what processing docs.microsoft.com uses to generate their pages? Instead of adding yet another custom documentation step, I'd prefer stealing someone else's if possible.

[joelmartinez]

docs.microsoft.com uses a conceptually similar system to xamarin's docpub ... which is to say they can publish docs from a group of markdown documents. We are literally right in the middle of migrating our guides over to this system, so it will be as simple as depositing the markdown documents in a github repository and they will be published.

[conceptdev]

You can see if you click the _Edit_ button, the source is basic markdown with YAML header info.

https://github.com/dotnet/docs/blob/master/docs/csharp/misc/cs0841.md

if the source content is actually a single-file XML or something), you'd need a preprocessor that splits it up into these individual markdown files... but from that point, it's super-easy to get published. we can create a private or public repo for the purpose...

[spouliot]

@conceptdev thanks for the link - we'll have a look before going forward

As for a repo we want to keep this inside our main repo - just because it's the easiest/safest way to ensure no new/updated error code ever gets committed without documentation :)

[VincentDondain]

Love this proposal!

Couple of things:

Making global changes, e.g. bugzilla to GitHub issues, requires a lot of changes;

Not sure I understand what you mean here...

Add a markdown template for new errors in docs/website/

xamarin-macios/docs/website (I thought you meant in the documentation repo for a second :P

---

One thing I'd also like to change is the msbuild errors codes: https://developer.xamarin.com/guides/ios/troubleshooting/mtouch-errors/#MT7xxx_MSBuild_error_messages

Right now they are MT7xxxx. The msbuild errors are from the iOS/Mac msbuild tasks, not from mtouch so it doesn't make sense to use MT for them. This was done mostly because we only had mtouch-errors to document errors and because that was already plugged in VSMac.

Not sure which prefix is best. If we really want to merge those errors with the mtouch errors we could rename MT errors to XI errors and XM for MMP.
Otherwise maybe we can just go MSB (but that conflicts with actual msbuild errors). https://msdn.microsoft.com/en-us/library/td545fab.aspx.

[spouliot]

@VincentDondain

Not sure I understand what you mean here...

How many references to bugzilla do you see in the mtouch-errors web page ?

One thing I'd also like to change

We are not changing any code or prefix. Their value is their searchability as questions/answers, blogs, bugs... have been using them for many years.

[VincentDondain]

How many references to bugzilla do you see in the mtouch-errors web page ?

Ah got it, and you address that with the suggested macros.

We are not changing any code or prefix. Their value is their searchability as questions/answers, blogs, bugs... have been using them for many years.

Oooooookay never mind then.
Maybe since we're going to have a main page leading to all the individual errors we'll be able to better highlight MT7xxx are msbuild errors. One of the macros could inject a special header or banner for the MT7xxx error pages too.