Agile technical documentation, an invaluable helping hand when you need it the most

Welcome to our regular session of Lessons Learned. Today we will focus on backend issues.

The standard software development process requires us to focus on problems, analyze them, apply a systematic approach to finding solutions, and manage lateral solution ideas that sometimes just jump out of nowhere.

The software developer often needs to dive in and out of various abstractions to figure out the best place for a new feature or fix a bug. Following the decision tree quickly exceeds the human working memory capacity and it’s natural that people start to take notes. Or not.

In this article, I will defend the simple activity of taking notes and suggest how to take them in a way that they can be most beneficial for you and also reused by your teammates.

Why should I care?

It’s complicated. It depends on your situation and ambitions. With proper just-in-time documentation:

  1. you will gain an unhealthy advantage over your colleagues
  2. you will be able to solve more in less time
  3. you will be able to do more complex things alone
  4. you will gain an ability to make strong and complex arguments seemingly out of thin air
  5. you will save money for your client/employer e.g. by documenting the decision process you can limit recurring efforts in the wrong direction

Taking proper notes is thinking on steroids. It’s a self-improving process that opens previously closed or even unknown mental doors. But:

  1. intuition will lead you to think it requires more work, but the fact is clear: it saves time but you will need to fight that negativity
  2. when you share your documentation it brings new responsibilities like adjusting the language to your user
  3. you will be inundated with new ideas all the time, it is hard to forget ideas that you have properly documented once, your lateral thinking idea pool will grow and grow to your benefit

Always start with mapping

Outlining is a method to aggregate ideas in a tree-like, linearly sequenced fashion. It is fast but mind mapping is even faster. With a mind map, you can outline without sequencing which is consequently less work while you still preserve the advantage of the quick rearrangement of ideas and their parent/child relationships.

Mind mapping on meetings will give you the advantage of an “out of the blue” argument based on your ad hoc overview of the discussed subject. When you analyze a new problem it allows you to persist collections of ideas and relations between them that frees your working memory which then can be used to solve e.g. some particular, deep technical issue. Once solved it easy to get back to your analysis because you have your map. Having a map vs. not having a map is a simple advantage that you can have over the others without the map. Why not have it all the time?

You can read many books about mind mapping. If I were to distill their content into one sentence it would be:

“collect ideas as aggregates of other child aggregate ideas to free your working memory to work on details.”

I recommend reading at least one book or article about basic mind mapping techniques and use a program called: freemind.

Once your notes are stored as a mind map you can progress in your technical documentation game toward knowledge sharing.

Progress with linear outline

A mind map can be quickly rearranged to provide a linear outline. This is the moment when you start to prepare your thoughts to be consumed by another human. It’s best to store the outline right away in the git repository, just next to the code you are going to add/change. That leads us to the storage format. Time-proven and the preferred way is to use shorthand markup language like Markdown. Markdown renderers, however, provide heterogeneous outputs e.g. markdown written for GitHub will render differently in pandoc, GitLab, etc. Asciidoctor provides a viable alternative. While allowing you to write with a handy shorthand markup you get:

  1. one standard of interpretation
  2. conversion to DocBook format that allows preparing big technical documentation documents
  3. no-fuss multilevel nested lists with annotated code listings
  4. in-document references
  5. and much much more

Once you start to write bigger technical documents you’ll surely reach Markdown limitations so it’s good to know that Asciidoc is here to take over and solve the problem.

Enrich with pictures

It is widely known that pictures are easier to consume than text. Once your documentation grows in size and complexity you will inevitably need a way to provide graphical guides to your readers. But UML is dead, what now? There is a way. There are a method and self-documenting notation that solves the UML learning curve while delivering similar informational value. That method/notation is called C4Model. Not only is that a method but a software ecosystem as well. There is plenty of commercial and open-source tooling that you can use to generate nice, informative pictures about your software. Having a diagram generator incorporated with your build project ensures that you can update diagrams along with code updates that give you miles ahead advantage over legacy tools like Enterprise Architect just because your architecture documentation lives. How many dead Enterprise Architect models/diagrams have you seen? Me- plenty! Usually, there is also no quick way to update the outdated diagram as you change the code.

Live it

As with everything in software your technical notes should live. Treat it as code. Remove obsolete parts. Refactor. Using the markup language and git repository storage will allow you to merge documentation review with code reviews to ensure everything is well documented over time. It's good practice to have an “update doc” step in your Definition of Done. Learn to think in maps. It pays off.

___________________________________________________________________

This is the first session of 5 lessons learned in backend. If the you found this article interesting, look up also the areas where we help our customer to prevent technical debt. Stay tuned for the next part!

Agile technical documentation, an invaluable helping hand when you need it the most was originally published in ableneo Technology on Medium, where people are continuing the conversation by highlighting and responding to this story.