docs requirements
All organisations need the ability to share knowledge and written communication is one of the most scalable forms. But in many orgs, docs don’t get the love they need to succeed.
Writing is hard and I’ve seen many engineers that don’t think that being able to write well is a skill that’s useful. I think that written communication is the most important for if your org wants to scale without huge meeting overhead. I don’t want to touch on what makes good writing, or even what makes good documentations. Instead, lets look at what environment your documentation needs to succeed and get the love it deserves.
Requirements
1. Plaintext
Docs and documentation should be written in plaintext, and preferably markdown. This gives the benefit of the content being entirely transformable into different delivery formats. It also avoids lockin if your hosting / editing platform goes down.
2. Version controlled
Documentation should be version controlled. You should be able to track that changes and history of a document, and it should go through the same review processes that your code does. For all the same reasons; review, knowledge share, etc.
3. Hosted
Documentation should be hosted, and not in github’s file viewer. It should have it’s own domain name and should be treated like a product.
Static site generators are becoming increasingly full featured and mature, so there’s really no excuse for not taking your markdown files and rendering them into a site.
4. Searchable
If documentation is to be useful, it should be searchable. Full text search is great, but perhaps being able to settle for just header search is acceptable.
VuePress
Recently I’ve been using vuepress, and have installed and migrated our docs site from confluence to markdown and vuepress.
It satisfies all of the requirements above, and also allows insertion of vue components to extend it’s funtionality.