Ask HN: How does your team handle knowledge documentation?
We are currently going through a rethink of our documentation (not for customers, just our internal processes, tools, etc.). Currently we have a docs directory in the root of our project repository which holds a bunch of markdown files, but we are beginning to grow out of this. Keeping links accurate and update to date isn't too much of a challenge, it's the barrier to entry. Filing a PR to make a minor documentation change is just too much. We could have the documentation in a separate repository, but if we are going to be making this leap, we want to be sure we are using the right tools for the jobs.
The way we see it, we are going to end up requiring at least 2 different types of documentation. The first is our deep documentation of our tools. This explains exactly what it is, how it works, etc. and is designed for people who want to work on these sorts of tools, not with them. The second is a quick fire Q&A. "I'm having issue X, how do I fix it?" Think StackOverflow.
So, what does your team do for these challenges? How effective is your solution? What do you think would be better?
92 comments
[ 149 ms ] story [ 3024 ms ] threadI would suggest adding the use of Doxygen to your projects. It supports Markdown files as well as Markdown syntax in your code comments. You might find that a lot of what you are documenting in the separate .md files could be a notes or remarks section of your method class comments. This will remove the separation of technical documentation vs. help/FAQ comments by doing all of the documentation in the code. You can then add Doxygen to your build, so that building the project refreshes the documentation. Doxygen can be configured to produce a online html version that can be deployed to an internal web server for quick reference. It can also build .pdf, rich text documents, and unix man pages.
Then if you use Continuous integration/deployment, when you deploy to test, UAT, then eventually production you deploy the official documentation that was generated.
The challenge with all documentation, is, Actually doing it. So it should be part of your SDLC documentation and process. the project/task/request is not done until documentation updated. Make it a checklist item that needs to be reviewed in code reviews. Doing the technical and help/FAQ all in code comments makes that easy.
cheers!
A simple Q&A document is failing us as well due to the fact that all commits to our main branches need to go through PR which puts in a high barrier to entry for what might be a minor change. It just discourages collaboration in so many ways.
> the problem is more for processes. Things like "How do I create a build from my commit?"
With well set up CI and automated builds, would you need this documentation at all? Could other processes which you currently document also be automated?
In my (limited) experience there's no great way to handle documentation, apart from reducing the need for it as much as possible.
The team I'm on (as a PM, I'm not a programmer) used to use Confluence for almost all technical documentation, apart from the odd Readme file. We use it for product, product range and other team documentation too, which makes choosing sensible top level hierarchy difficult! I don't recommend trying this.
But we finally have decent automated builds in place, and it's made a world of difference. We will soon have decent CI set up too (with Gitlab), at which point lots of project specific technical documentation will move to Gitlab wikis, living alongside the repo it relates to.
We have that. But how would you know that we have that without documentation telling you? How would you know where to find the resulting builds or to check the status?
> We could have the documentation in a separate repository, but if we are going to be making this leap, we want to be sure we are using the right tools for the jobs.
If you haven't considered this yet, it would be very easy to set up a Mkdocs[1] site for testing, using all of your existing documentation. Should be as simple as making a new site and dragging your current docs folder contents into the docs dir. It has good search built in with Lunr[2]. Try the Material theme[3] if looks are important.
[1] http://www.mkdocs.org [2] https://lunrjs.com [3] https://squidfunk.github.io/mkdocs-material/
* we use Slate for API docs, Google Sites for company documentation (and some Google Docs) * am thinking about using a forum for Q&A e.g. Discourse [2]
Longer:
We've also been going through some thinking on this. At the moment we have an API docs page using Slate, and a Google Sites site which contains a whole raft of documentation. We still have some stuff in Google Docs as well.
Our problem is that not all the team is part of Engineering, so keeping stuff in the repo isn't really ideal (hard to edit). Google Sites is fine but its main selling point is easy access to Google Auth. I have a thread on HN about this [1].
One of the things I have been thinking of is setting up a forum like Discourse [2] for Q&A. Sales often has product-based questions, and vice-versa. In my view, this beats other ways of asking questions (e.g. Slack) because there's no time pressure to answer, and unlike "office-hours" style meetings, it's automatically documented. The only problem is that it is yet another tool.
[1]: https://news.ycombinator.com/item?id=12540678 [2]: https://discourse.org
That's one of the main horrors we are trying to avoid. We'd like to have a single location to track both kinds of documentation ideally, but realise we are probably going to have to make compromises. Tools which keep things in a standard format will ease migration in the future, so something like Slate would be nice and looks a little better than our current way of "Go view the file in Github".
Confluence is a very good wiki. There's no wiki that creates good structures for you automagically.
There are various orthogonal concerns to deal with when documenting software development with Confluence:
+ knowing the underlying platforms / technologies your project uses
+ architecture / design of system (which will evolve over releases) -- Gliffy plugin works well for illustrations
+ documenting releases
+ engineering-level precursors to user documentation
+ meetings -- high-level overview of discussions, decisions, resulting actions
+ Confluence wiki integration with bug-tracker, source code repositories
Without an up-front design one will run into problems. Even worse if managing several projects.
To solve that problem we started with a "doc" directory in each repository holding multiple markdown files for each topic. That way all of our developers are able to find the information they need (even without an internet connection).
If someone has "solved" creating a good way to capture tribal knowledge, I'm all ears. But it's not the tools being used that are the issue or the solution.
My startup is actually working on this exact problem: https://tettra.co
Our philosophy is that knowledge should be fast to capture, accessible from your communication tools (Slack, etc) and open by default for everyone on your team to suggest edits because most knowledge goes stale in other systems.
Would love feedback from the HN community. We're documentation geeks here and love talking about this stuff.
If you're interested in using the product, we can offer a special HN discount of 20% off the first three months. Just shoot us a message in the chat. I'm on there right now.
Want to shoot me an email and I'll send you an update when it's live? andy [at] tettra [dot] co
And Slate was just a pleasure to work with.
It is great for one thing, everyone can edit it with just their browser. Today, however, you have more options that can do that with a Git+CI backed auto deploy on change.
Right now it's a GitHub wiki in our "infrastructure" repo (which is basically all the bits and pieces that don't fit anywhere and don't have a proper repo of their own). We migrated to this from: "several github wikis, each in the repo of the project" - but often you have overlap and it was bad to find stuff.
Pros:
- easy backup (git clone)
- markdown
- easy to get started, "good enough"
Meh:
- searchable only with a browser extension
Contra:
- some coworkers don't like the github wiki
My dream (never happened in any company as of now) would be a single document (think: the manual), hopefully editable in a proper way (I am not sure if checking in changes in a doc/ folder in a code repo is the way to go for <10-20 people) that's hopefully displayable in a browser (and not a PDF, and ESPECIALLY not a Google doc) with cross-references.
Blog post is from August 2016 "You can now search for wiki pages from either the main search page, or within a repository."
Guess I made up my mind about that 1-3 years earlier and have used the extension ever since :) Ah well, one click less at least.
reads markdown
has an online editor available
stores in git
and is searchable.
I was about to make this same joke. Glad to hear that everyone is just as screwed on this.
I hate it, because it's slow.
but I do see it has some benefits, for example, it automatically generates a content table. so content discovery is easier. it is also designed to be a document system for a software company. you can use it to create meeting notes and tag people.
but overall, I liked mediawiki, the problem with it is, it's hard to make sure things are up-to-date. and it's difficult to do content discovery.
* Super bloated and laggy
* Hard to get your data out/migrate to some rival system. Did your technical writers spend a bunch of time typing strings into a table using the Confluence table building GUI, and now you want that data as a .csv? Too bad, hope you want to spend half an hour in copy-and-paste + reformatting hell.
* Impressively broken search (e.g. if you create a page named "foo" and then search for "foo," you'll often get pages of unrelated results that do not include your page called foo)
* Can't natively show typeset math. Doing so requires plugins that are somehow both expensive, broken, and only compatible with narrow ranges of Confluence versions.
* Gross nonstandard markdown dialect
These are just the shortcomings that I can think of right now. However I think even Confluence is probably better than submitting PR's for docs changes as the OP mentions, since at least it's a wiki.
Easy to edit, easy to maintain, good search capabilities, plenty of ways to extend.
Edit: for updates of mediawiki use installatron, for structuring documentation you can use categories.
- wide screen support (paragraphs to across the whole screen)
- Every page is a folder and the add-button is visually above the current page in the hierarchy, but creates a child page. Easy for techies once they figured it out, hard for new people and the rest of the company.
- no tree-view by default
- comments can't be seen in edit-mode
- no markdown
Biggest pro though:
- collaborative editing in a wiki (and still a dedicated edit-mode so work in progress remains hidden from those trying to just read the resource)
Do not tell them what tool to use, let them own your knowledge base and make their requests for information understood to be P1 priority.
Imagine explaining why it is not necessary for the project to have a database expert, a back-end expert, or a web expert... but you definitely need a wiki-pages-organizing expert.
I really never thought of actually having a person responsible for internal corporate knowledge, but it makes a lot of sense!
At edX we have information spread between Confluence and Google Drive. Search is not ideal for either. Information sharing is not great.
We created Teamemo (https://teamemo.com) because knowledge management should be easy, fast and fun.
We have people get assigned tasks from other projects from time to time, and they start picking up bits and pieces of the projects from that. And we have an internal wiki that documents some things that people aren't very good about keeping up to date or making it comprehensive.
Also some of our software has gone through rewrites that has cleaned up the architecture and made them easier to understand and work with, without documentation.
But there's still way too much locked in people's heads. We've lost quite a bit of it, too, as people have left over time. I know we're trying to convince a client to shift over to newer versions of our software, because we no longer have anyone that knows anything about the tech the legacy legacy software was written in (it's legacy software that predates our existing legacy software).
My name is Omer and I am currently building a knowledge documentation solution called Scribe (formerly Mindflow.ai).
Scribe runs in the background of your development environment and creates documentation based on your workflow. Additionally, we allow for users to easily create their own documentation in an intuitive, easily searchable fashion.
During Y Combinators Startup School we launched our Alpha product, and we are currently building the beta version of our product. If this sounds like it can help, you're more than welcome to sign up!
http://mindflowai.com
The information split is very much as you describe between canonical and ephemeral. For the first case, the defacto tool for medium size companies (25-1000) is Confluence (large companies lean towards a custom intranet). Confluence is accessible to the entire company, not just engineers with git and markdown knowhow, it is also well established, very reasonably priced and can be deployed on cloud or on premise. There are drawbacks such poor search and complex organization that makes it hard to find anything, but there is not a clearly better solution at the moment, though there are a few startups like mine trying to change that.
For the second case, companies have tried to deploy an internal StackOverflow / Quora, some homegrown or using open source tool but unless tied to a specific workflow (like all hands Q/A), they are eventually abandoned. The issue is a lot of duplication of content that also changes very often. So long term storage is not as valuable as just removing the initial friction and what seems to work best is an ephemeral solution like a dedicated Slack/Hipchat/Teams/Mattermost/Gitter/Zulip channel.
About the only downside is that sometimes documentation gets outdated and you have to hunt down the current version of a process, but that beats the alternative, where nothing is documented.
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.
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/
Really how can we expect anyone to properly document anything when not specifying how? It is so obvious now.
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
TOOLS
Until recently, we used a combination of Documentum and EPM (Enterprise Project Manager). The intended workflow was to have all documents start in EPM as part of the initial project implementing/building whatever product. When the project closed then the developer was to copy the documents across to Documentum. It was simple in concept. Due to technical shortcomings, it was not. I stopped even trying around 3-4 years ago.
Documentum was a technical horror show. Ten years ago, and for a long time afterward, it supported only one browser, I believe IE. Architecturally, it seemed to use a Java applet for login and, upon successful login, it downloaded an app. Of course, the app wanted a specific version of the JRE locally. But, the real nightmare was authorization. One day you had permissions to update “cabinets” for your documentation. The next day you didn’t. No explanation.
EPM had authorization issues similar to Documentum’s with the added bonus of a project’s link not working all the time. One day you could use the link, which the PM sent out at the start of a project, to access the project workspace. The next day you couldn’t find the project workspace.
Currently, we're moving into a SharePoint site that is more promising. It provides Wiki capability for quick reference items, as well as, a repo for more involved documentation. Apparently, it provides versioning, but we haven't explored it yet.
TYPES
Part of the problem with the subject of documentation is that different groups want different types of documentation. Somehow, the developer is supposed to understand the needs of each group and produce a document tailored to those needs.
Operational people want information on jobs and job dependencies. Support people want lists of things to check and try in case errors occur. (Developers are inherently bad at documentation for customer support. The problem is that we know how the system is supposed to work, so we’re blind to its shortcomings until a user finds them. Rather than my writing a support document upfront, I prefer meeting support people periodically so they can ask questions and develop their own document.)
Management wants everything, all at once. They want it in the amount they want it, summarized, but detailed enough that they can feel like they’re a help during outages and architectural meetings alike.
Users want to know every step for every task they need to accomplish, as well as, what to do in any anomaly, like not paying attention to dialog boxes and hitting “Save” to commit information that they didn’t want to commit.
ISSUES
The major issues, for me, are keeping documentation current and writing for such varied audiences, nevermind having the storage system working against me.
- 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.