Ask HN: How does your team handle knowledge documentation?
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.<p>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).<p>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.<p>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, ...).<p>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.<p>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&amp;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.