Standalone documents may fulfil many goals (instructions, specifications, summaries, architecture overviews, etc.), but instead of focusing on strict names, categories, definitions and structure it’s better to ask for reason documentation must be written: why and for whom?
(From a developer’s point of view, no less important will be the tools, that we are going to use. More about it in another article.)
A good example why I think that formal methods might become a little obsolete is the example of today’s UML popularity. 10 years ago everyone attending university was taught about this analysis and specification language. I’ve got even a whole course focused on a project, where in a group everyone had to prepare a UML specification of selected part of system in design. Yet, to this day I haven’t heard of a single team actually using UML at work.
One of the reasons I encountered, that explains difference between theory and practice, is the raise and popularization of agile methodologies in IT. There, opposite to formal specification with UML, actual specification is developed during implementation phase (or even later, if at all). I will not go into details, as I haven’t experienced transition to agile myself (I’ve only worked in projects without a process or already in some flavor of agile). Instead, I would like to point you to Ernesto Garbarino’s article, where he writes about his experiences much more informative and entertaining, than I could.
So, today, when much less emphasis is placed on formal documenting methods, you, as a developer, probably won’t find many professional training opportunities, there won’t be many (any?) more experienced team-member to give some introduction, or, in the worst case, you may not even find any model example in you current project (because there is none, or they are indistinguishable for untrained eye, weather useful or useless).
Two questions should now arise:
Let’s find out!
If the target audience are also developers, it’s normal to use technical language in general, but be careful about overusing specialist terms from a narrow domain or related to a single technology. For example, I’ve once asked a question about expected id field value format, but instead the short and accurate answer I received description full of phrases from a framework I don’t know, from a language I’ve seen the last time 10y ago, and after reading all this, I only got more questions…
If you are a backend developer and the target audience are frontend developers, they probably don’t care about your technology stack, but would need a very strict explanation of available REST API, endpoints and payloads models.
When you are writing an instruction for less experienced developers, who are joining your team, then before you describe more detailed aspects, it might be very helpful to have a whole project overview prepared.
And if there is a need for step-by-step, specific component implementation tutorial, then there is no use in sending 30 pages describing your whole system.
If you are a backend expert, and you have rarely used UI, there is a chance that you are not the best one to write instructions for end users. If there is a tester in your team, they probably have much better knowledge about ins and outs of user interface. On the other hand, they may also be accustomed to less obvious parts of the system and focus too much on elements less important to the users. Consider asking for help in the business unit. Maybe the company should hire instructions specialist.
Your team might realize that there is some domain knowledge that only some members know better. If experts create documentation there is a risk, they will omit many important details, unaware that they are obvious only to them. On the other hands when novice is tasked with documentation of a module, they are forced to understand the domain and technology, and there is no risk that they would omit something important. In the worst case, they will write about too many details that aren’t domain knowledge. In such case, just extract these parts into introductory document for newcomers.
This is not only about documentation, but knowledge in general, and it has many names: Learning by Teaching, Feynman Technique, or best known to programmers Rubber Duck Debugging. I would really like everyone to give this a try, whether you have kids learning new material for school, you try to learn a new programming technique, or you found a fascinating material in a book about your hobby. Just writing this series of articles already helped me greatly improve some aspects of documentation in my current project.
It’s a common cognitive bias to evaluate our knowledge based on our intuition. But our intuition gives as a very general feeling, when it’s mostly a very nuanced knowledge, that matters. In context of documentation this becomes important when we are tasked with developing a feature in domain outside our comfort zone or when we are going to become a newcomer’s mentor.
So, one way to deal with such tasks is to just jump right into the problem, cause YOLO. The thing is, if you never knew or forgot important facts, you have to dig in projects code and history, when more important tasks are waiting and people’s time is wasted.
The other way is to prepare. Developing documentation is not the only way, as you may for example just spent more time consulting your teammates. But even then you can write everything down. This way, no matter what’s more important at the moment – gaining knowledge about system or expansion of product documentation on its own – you always achieve both things.
Not in every project there is a generic documentation for every client. Even then you may get a new case that only one client require. Then you may be chosen to create documentation for that client. If you have never done that before, what will you do? It’s not a trivial task, you can prepare yourself for in an hour of reading some promising article Writing Documentation In Three Simple Steps. What tools are you going to use? MS Office Word, or LibreOffice Writer? You will probably hate yourself for this (and your client too).
By spending even a little time on documentation once in a while, you are constantly learning a valuable skill. The same way we are coming back to our code to fix it, make it more readable and update features according to changing specification, we are now coming back do documentation we created, update it and evaluate quality of previous efforts. You should also be comfortable with tools you are using in this process, so by giving yourself time to learn, you are becoming productive by choosing better tools and mastering them.