4 ms·

I work in a department that develops and maintains an internal SDK used by internal BIUs to develop medical applications. Size of codebase is well over 1 Millio

I work in a department that develops and maintains an internal SDK used by internal BIUs to develop medical applications. Size of codebase is well over 1 Million LoC. We heavily user source code documentation for all public API which is enforced by our internal build tools (build breaks when undocumented code is found) and the review process (to check if documentation is proper). We have a searchable themed MkDocs page with a large number of “how to properly document X”. Reviewers actively place links to these pages in the reviews where source code documentation is not proper (style issues, lacking, no examples, etc). Goal is here to have a proper MSDN like source code documentation and site generated by Doxygen. Each release gets its own documentation, which is easy as it is just a source control revision. A second goal is to have most of the documentation as close to the code as possible so it actually stays well updated. Next to this we have a developer portal which is based on manually written markdown files. We are currently in the process of replacing our existing media wiki pages into markdown as well. Markdown is quite powerful as most people can easily read it, even with just notepad. In addition it converts to anything so it feels a bit more future proof. Right now we put it in a slightly extended mkdocs served site. We extended a bit for versioning and a landing page that links to separate mkdocs sites as the navigation becomes too cluttered if we put all of our layers and components in one site. Better to branch Early is what we found. So separate sites for database, infrastructure, system (multi-subsystem deployments), application development (wpf, HTML5,..),and for each subsystem (printing, auditing, reporting, data server, ...). The problem is already we notice the manual markdown is not properly maintained. I think this is a problem you never solve unless you hire people to do it full time. I.e technical writers. My personal opinion is that a stack overflow enterprise (on-premis SO) is more powerful. Nowadays people want to know “how” instead of “what”. A Q&A site with tons of questions and answers is much better than a one-way written developer portal. Also, other people outside of our department could also answer questions for us. As a benefit you learn where people struggle with your API or use it for things it was not developed for. Feedback is great here.

xaedes 9y ago
Do you mind to share what kind of X in “how to properly document X” pages you have? I like that idea and would like to do similar!
- bastijn 9y ago
  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). [1] https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/

xaedes 9y ago

Do you mind to share what kind of X in “how to properly document X” pages you have? I like that idea and would like to do similar!

bastijn 9y ago
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). [1] https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/