Don’t Document, Automate!

I’ve been writing and reading code for more than a decade. I believe I’ve seen it (almost) all. From enterprise, army-related, startups, open-source, and it all comes to one major thing — software project are never straight-forward, and mostly do not following a standard. That reality demands each project to its own ‘maze guidance‘; a written (at best) or verbal (at worse) explantation about how stuff works, why and how to get you onboard.
And that can get very nasty..

Some folks take the effort and write down a ‘wiki’ / ‘knowledge-base’ / ‘documentation’. It can vary from good descriptive content to lousy, outdated content.
Now, let’s assume we do have a well documented wiki, it’s still has a known pitfall — documentation does not stick as your software morphs. While your code continuously (hopefully) gets refactored and morphed, the documentation mostly does not. And that’s a big problem on the long run.

Having a documentation is a good thing but not ideal for the long-run. It can get even worse than that; I’ve recently encountered a group with a strange perception that prefers keeping the knowledge in their individual minds, as they believe “the best way to learn is by doing”, and by “doing” they mean scrutinize into the codebase.
To me, that’s just the worse job-security ever. Keeping the knowledge owner in a position he’s needed.
First, it’s not scaleable, dependent and prone for mistakes.
Second, essentially, when other engineers don’t have a proper documentation they pave new ways, ending up with multiple overriding methods to do same thing.
Third, it’s simply unprofessional.

I believe there is a proper way to on one hand have a ‘manual’, but one that also does scale and change when you code changes. Enter automation!
When done right, you’ll eliminate the need of writing/maintaining a a flaky documentation. At least minimize it to the bare minimum.

To be able to successfully apply automation to the various parts that a given documentation can address, we’ll need to break down into couple sections:
1) User guide
2) Architecture
3) Deployment/Setup
4) API (design & docs)
5) Coding styles
Each of those should be treated differently.

User guide intended to explain how to use the software, how different portions play together and what dependency there is to start off as a user. If the project does not have a good UX, it’ll have to compensate with interactive & informative walk me. Here are couple good tools for that:
- walkme
- userpilot
- swipeguide

Architecture intended to list and map the components and how they interact. The best way I’ve learned is to have well defined APIs and interfaces, plus architecture that is self explanatory, just as code can be. It should be easy to follow the interactions within the code itself. Tools/techniques you can use:
- Design and iterate using UML technique
- Visualize before implementing using Miro.com

Deployment/Setup are instructions, usually os specific, how to get the project working, whether locally or on a server. That area is already well covered by techniques and tools to automate machine provisioning and scripts. Best way to go, which is already an industry standard, is to containerize everything! The ability to deliver pre-built image and setup in no efforts will eliminate most of manual operations needed.
- Docker

API intended to describe how to use the various endpoints, functions or modules. Having self explanatory code is best way to go, or at least generate documentation from the code itself. A good starting point would be to carefully design the api though-out the whole flow. Here are couple tools to assist with that:
- apidoc
- Swagger
- stoplight
- Postman

Coding styles intended to make sure all engineering members are aligned and produce same styled code. Some rules can be enforced using existing tools in the market, some may require writing a custom script. And that’s never a bad thing, probably the best way to automate. Here are couple tools available:
- StyleCop
- FxCop
- eslint
- Prettier

All in all, ‘technology’ is the idea of taking manual repetitive work and automating it so we could focus in more important/interesting tasks.
Documentation/knowledge-base is no exception.