Calling all developers: we need better documentation tools.
Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code.
We writers enjoy writing, but when it comes to docs as code, not everyone enjoys dealing with version control (git) and associated workflow processes. Sometimes, it is an overhead and could be time-consuming.
I am not arguing against the docs as code philosophy. However, my beef is with the lack of tools we writers have at our disposal. When we use `git` for documentation using existing tools, managing it becomes harder and harder with time. It often becomes a task in itself to manage and control pull-requests (merge-requests), branches, commits, history, and what not.
On a good day, when I want to write some content, I hate dealing with these pesky tools trying to fit what I write according to the capabilities of the software. I think it should be the other way around.
I would love a tool that could abstract away all the git related things that I invest my time in and possibly let me focus on my writing. I haven’t come across any existing tool that does it. The closest I could find was Glitch. It beautifully abstracts all the git related aspects and presents them in a human-friendly view, which they call Glitch Rewind. Glitch is not a documentation platform, but being a documentarian at heart, I couldn’t stop myself but search for a docs tool that I could efficiently run on Glitch. I tried multiple open-source documentation tools and settled on Docsify. Docsify is easy to use, uses markdown files, and supports a plugin structure to enable extension if required.
Sample documentation site (Docsify) running on Glitch: https://glitch-docsify.glitch.me/
Benefits of this approach:
1. Minimal learning curve.
2. Version control without git commands: Glitch’s rewind feature is super awesome, it allows one to jump back in time and undo the modifications.
3. Cloud-based editor: Cloud-based editor with real-time editing.
4. No need to worry about servers and setups. Changes are deployed instantly.
However, all that glitters is not gold.
It’s fantastic but it still lacks a few features which are a must for any documentation website.
1. No support for branches.
2. Edits are live instantly, and so are your mistakes.
3. No approval process or reviews before publishing.
Glitch isn’t a tool for documentation, and these drawbacks are not real drawbacks of Glitch itself, which brings me back to the point I want to make.
We do not have human-friendly documentation tools around, and there is a need for one.
Are you a writer, what do you feel about the software you use for documentation? Do you agree or disagree with anything I say here? Please add your comments and share this with developers. Hopefully, someone will listen, and in the future, we will have better tools at our disposal.
