Sharing the knowledge company-wide is an important part of the culture. The more people work together, the more questions are asked over and over again.
Usually a simple GitHub repository or a Confluence instance solves this problem. However, I believe that software and product teams need a little more tailored solution.
The problem with all Wikis
The biggest issue with all Wiki softwares is that they completely ignore software diagrams. I can’t imagine my everyday work without drawing architecture or user flow charts.
Here’s a real chart from our recent Payment API discussions:
This is a crucial piece of internal knowledge that helps engineers and product people understand how the system works.
Drawing such a diagram in external apps, such as Gliffy or Draw.io, is a daunting task. Here’s why:
- Writing project description accompanied by diagrams requires at least two apps: text editor and diagram editor.
- Editing a complex diagram means moving lots of blocks around to make space for a new one.
- There’s lots of overhead needed to embed a diagram. One has to log in to the app (remember the password), draw the diagram, save and export, upload the file in the editor, and finally publish. It drives people off keeping the internal knowledge base up-to-date, only because the task is not a no brainer.
I think there’s a better way. And I created a simple project that proves this. Meet Octopus.
The best part is how easy it is to build a diagram. Thanks to viz.js library you can draw a diagram with a plain text, such as:
"Web browser" -> "REST API" -> "back-end server"
and the diagram is there! That’s a huge time-saver in comparison to all external diagramming tools you would need to use otherwise.
Diagrams are highly customizable thanks to the extensive DOT language documentation: http://www.graphviz.org/content/attrs. Octopus supports all of the options!
Octopus was build in a few days from scratch and open sourced. Everyone can start using it within just a few minutes of setup.
You can download Octopus from GitHub: https://github.com/livechat/octopus
Good luck with keeping your company-wide knowledge up to date!