Updating error documentation generation/workflow
- Dominant language
- C#
- Stars
- 2.9k
- Forks
- 576
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 96
Description
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;
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.