Documentation in your organization

Documentation is about structure and discipline.

Is it possible that I don’t need to create documentation?

I can imagine only one situation when the answer to the above question is positive — and it’s when you are working on something totally alone, have all of the things in your head, and you do not need to share the context with anyone, but even then I would be very cautious on deciding to not create any documentation. Usually, when you start a new project — you are writing at least a README file, which is — maybe that’s a surprise — documentation. In the scenario described above, you shouldn’t make it to your future self. Leaving some documentation for “future” generations is always a good idea, and to be honest — you never know, how the project will evolve and when the documentation will be needed.

The Structure

The most important and the first question you need to ask yourself is: Who will be the main documentation beneficent? In other words — who will be reading it the most. The answer to this question may differ depending on your organization's needs. Imagine that you have a small five members technology team, and there’s a decision that it needs to double in the next six months. In such a case, the obvious answer is that the documentation should be created for technical people that will join your organization soon. By creating such documentation you can save yourself and your team a lot of time, but what’s also important — it can be used in the future when the technology team needs to be scaled once more.

Business documentation structure

Business documentation is tricky — cause it’s internal as well as external. What do I mean by that? Well — part of the documentation is a so-called requirements definition, which in short can be described as business expectations towards the software we are producing. This side of the documentation is internal. The output side is related to the end customer of the software — it’s about answering the question: how to use the software? And I also believe and like good UX, but in complex systems, you can create the best UX in the world, and still, you will need some guidelines — where to find the switches, and what will happen when the user clicks this button. This part will be called external.

  • easy interface, which can be used by non-tech people, thus either a web interface or easy to use desktop application
  • documents should be accessible only within the organization
  • ability to export the documents into formats like PDFs to allow sharing with other stakeholders if needed

Technical documentation structure

The biggest myth here is that “you don’t need documentation at all” or in other words: “I am writing self-documenting code”. If you still believe in that you should definitely reflect on these thoughts once more. And don’t get me wrong, code can be a great source of documentation, and usually, it is, but after some complexity threshold it’s simply not enough.

Technology documentation

And finally, we are in the bucket that it’s valuable only for technology division, cause level of details here is impossible to be understood by other members of the organization. If you think about it, there’re multiple sources of this kind of documentation:

  • wiki pages (usually delivered by VCS)
  • personal notes
  • f2f conversations with other developers
  • the repositories: structure, READMEs
  • infrastructure-as-a-code-like solutions

The Discipline

Documentation without discipline is not existing. Maintaining the documentation can be a significant part of the job and I think this is the main reason why people not doing that. In the industry, there’s this bias that engineers do not make documentation — but I think it’s only one side of the truth, product roles are struggling here too.

Final thoughts

I’ve planned to write few words about documentation in the organization, but actually ended in touching the Knowledge Base management areas, the observations gathered here are based mainly on my experience, I’ve read few articles about it in my lifetime, but I am not considering myself as an expert here, what I do know however that context and knowledge is extremely important, and it simply can not be ignored, cause when ignored it will blow up in the future, causing the damage, that is hard to assess. The main areas discussed in this article are presented on the graph below:

The documentation areas you can focus on.

Software engineer, technology enthusiast, common sense lover, serial co-founder, and a father of two.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store