I wouldn’t mind but our bureaucracy organ does :(. Whilst technically it is only moving the markdown files and CIconfig from our private gitlab to a public one, the bureaucracy involved with it prevents me from doing it today. I would have to pull a part of our source code which is under strict regulation, and I try to only start that process when I absolutely must do so (subsidiary projects mostly).
The contents are free to describe though. Essentially you would find a large number of pages on all language concepts for our main languages. So “how to document a method”, “how to document a property”, classes, namespaces, you get the idea.
Next, we have a very clear setup in our documentation pages. All pages and sections on pages have permalinks. The idea is that you can redirect people to the exact information they have to read. Every section always starts with three examples. The examples are different enough to be applicable to say 80% of the cases. This means most of time a developer does not need to read more than the examples, c/p one and adjust to his specific case.
After the example cases the different aspects are discussed that should be in. This includes rules like “use the 3rd person when writing descriptions”, “use present tense”, “start with active verb” but also “include minimally one example in the format above” and “never use the name of X in the description”. (I.e SetSomeCrypticThingOnlyWeUnderstand() // sets the cryptic thing << not helpful). Basically a checklist. Typically we have DO, Don’t, and AVOID listings.
After that (bullet/checklist) usually a paragraph describing the rationale for documenting like this as well as other information not captured in the examples or bullets.
Sometimes after this there is a section of “also consider” where we capture issues of the past. E.g “when documenting X that uses units, specify the units.”. I.e if you have a property Angle document it is degrees or radians. That same page would probably have a paragraph on should you name “Angle” or AngleInRadians or some info on avoiding ambiguous naming of properties.
I’d say the biggest game changers are the permalinks, good golden samples at the start of each section and in some cases bullet lists. The description paragraph is optional.
All our pages are markdown pages served on Gitlab Pages (on premise deployment) as static site built with MkDocs and Material theme (slightly customized) [1]. All pages include an “edit on gitlab” button so users can edit the pages in their browser without downloading any tooling. A CI setup will auto redeploy on commit/push. If clone the repo and you download MkDocs locally you can of course write with live reload etc on a local server (MkDocs serve).
O, and have a great search functionality and decent responsive website that is easy to read (good font, colors, syntax highlighting etc).
The contents are free to describe though. Essentially you would find a large number of pages on all language concepts for our main languages. So “how to document a method”, “how to document a property”, classes, namespaces, you get the idea.
Next, we have a very clear setup in our documentation pages. All pages and sections on pages have permalinks. The idea is that you can redirect people to the exact information they have to read. Every section always starts with three examples. The examples are different enough to be applicable to say 80% of the cases. This means most of time a developer does not need to read more than the examples, c/p one and adjust to his specific case.
After the example cases the different aspects are discussed that should be in. This includes rules like “use the 3rd person when writing descriptions”, “use present tense”, “start with active verb” but also “include minimally one example in the format above” and “never use the name of X in the description”. (I.e SetSomeCrypticThingOnlyWeUnderstand() // sets the cryptic thing << not helpful). Basically a checklist. Typically we have DO, Don’t, and AVOID listings.
After that (bullet/checklist) usually a paragraph describing the rationale for documenting like this as well as other information not captured in the examples or bullets.
Sometimes after this there is a section of “also consider” where we capture issues of the past. E.g “when documenting X that uses units, specify the units.”. I.e if you have a property Angle document it is degrees or radians. That same page would probably have a paragraph on should you name “Angle” or AngleInRadians or some info on avoiding ambiguous naming of properties.
I’d say the biggest game changers are the permalinks, good golden samples at the start of each section and in some cases bullet lists. The description paragraph is optional.
All our pages are markdown pages served on Gitlab Pages (on premise deployment) as static site built with MkDocs and Material theme (slightly customized) [1]. All pages include an “edit on gitlab” button so users can edit the pages in their browser without downloading any tooling. A CI setup will auto redeploy on commit/push. If clone the repo and you download MkDocs locally you can of course write with live reload etc on a local server (MkDocs serve).
O, and have a great search functionality and decent responsive website that is easy to read (good font, colors, syntax highlighting etc).
[1] https://squidfunk.github.io/mkdocs-material/