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.

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.

I work with a large (multi-billion, multi-national) tech company that has a big problem with knowledge management.

My job involves consulting to lots of customers in different industry sectors, and the one small, sad comfort is that almost no one does documentation management well.

Currently if I want some specific tidbit of information I can consult: our knowledge base (bespoke), our collection of product PDF's, salesforce documentation repository, quickbase documentation repository, an aging wiki (twiki), private stash of documents created by colleagues, mailing lists (a subset of which are indexed and accessible from the wiki, otherwise you can only go back as long as you've been with the organisation, and hope you've been subscribed to all the right lists), sharepoint (meant to replace the wiki, but two years later, and no), our learning management system, yammer (seriously), bugzilla, our customer support forums ... or I think about who might know the answer and email them.

My advice as a result of this:

Even if you don't hire a librarian, at the very least appoint a curator -- ultimately you need someone who owns your documentation, and the design and management processes around it, and can encourage/force people to update it, continually reduce redundancy, improve quality, etc etc.

Be wary of your current thinking " We'd like to have a single location to track both kinds of documentation ..." - specifically that there are only two kinds of documentation. Or indeed only n kinds of documentation.

It's easy to fall into the 'let's build a new system to encompass the others' trap (insert obxkcd) and hard to fight it. If you do go down that path, ensure the content from old systems are fully migrated (3 years after it's been 'retired' our twiki is still the best place to go for some things). This is hard - it's rarely budgeted, and involves tedious and/or impossible work.

I suspect it's impossible to have a single system that will manage all your institutional knowledge -- I know many people are working on solving this from both directions, but I don't believe there's anything suitable now.

Whatever you choose it needs to have a low cost of entry for non-technical staff to update, while not frustrating your technical types. This is hard to find.

In 2007 I set up DekiWiki (based on mediawiki, but since abandoned) for a medium-sized gov agency -- in 2013 when I caught up with that team I was surprised they were still running it. It was internal only, so they weren't so worried about lack of patches, and they hadn't found anything better in the interim.

Out of that experience I'd suggest that whatever you do go with, make sure it's easy to extract your data, and that you maintain your own full copies of product documentation just in case the product is abandoned. Also - don't assume products won't be abandoned. MindTouch / Dekiwiki [1] was big in the mid 2000's.

[1] https://en.wikipedia.org/wiki/MindTouch

We just started using Guru (getguru.com) for our 13-person remote team (trydesignlab.com), and it's been quite effective. Some key features that we love:

- Simple UI with well-known metaphors like cards and collections — each task or process you have as a company can live in a separate card

- Tagging combined with lightning-fast search

- A bookmarklet that allows you to search your Guru knowledge base from any other site you're on (really handy for our support agents who want to look up a manual process without leaving their support workflow in Zendesk)

- A "verification" workflow that ensures your knowledge base is up-to-date (previously a huge issue in any sort of wiki / document-based solution — you never know if what you're reading is the latest piece of info, or whether it's been updated since). Cards can be assigned to an owner who can be reminded to verify the information on a periodic basis (e.g. every 2 weeks, 4 weeks, etc.), and anyone viewing a card knows whether it's been recently verified

- The ability to ask questions to individuals / groups within Guru, with answers turned into new cards. Instead of tapping someone's shoulder (or sending them a Slack message), we now ask for info within Guru, organically growing our team's shared knowledge base over time

Overall this has been a tremendous find for us. We had a number of core processes (support, operations, payments, dev, marketing, sales) that lived in various Google Docs (including one monolithic 'Process Guide' doc), but that system was growing extremely cumbersome to use. We strongly considered Confluence, but stayed away after a short trial revealed how bloated the product was — we knew ramping the team up would be a nightmare.

So far Guru's been a winner — would recommend giving it a spin.

Thanks for the feedback, and I 100% agree with you. We're working on it.

Want to shoot me an email and I'll send you an update when it's live? andy [at] tettra [dot] co

Best part is when they retire and then no-one knows anything about anything. Then the Company is forced to hire them back on as contractors (at $500/hr, minimum 25 hours, of course)