Documentation Tips— Introduction
Who am I to write you this?
Well, no one 🤷♀️ 👀
I am here just to share my thoughts and ways hoping it will help someone.
Boring introduction coming
(you can skip it, I’ll allow it😌)
Although, just to give you a bit of context, I think I can start with: I always liked to write, specially poetry and prose. Throughout the years I started to write more technical documents, such as papers and essays for university and of course my masters thesis. One of my coordinators gave me a lot of hints to improve my writing, which also helped shape my mind making myself more critical about technical writing. It seems, it developed in me some kind of sensibility to this topic, that brings a little and different value in my current work.
These days I am a solid documentation driver, as I am aware that it’s not a cool, easy to maintain task and everyone starts pushing it off, unless it is already instilled in the culture of the company. Nevertheless, I am always eager to help improve this process, try to make it less painful to perform or at least simpler to do so.
Everything I will state in this article is just based on my experience as a student and a software engineer. I am not here to preach, I don’t have the right formula for this, I have some kind of formula that may be useful.
No one likes to write. Well, most people, but everyone wants or needs to.
Why is it so important?
We work for humans, even if it’s through machines, we always need to express ourselves, to inform someone or just to share experience. The lack of communication or its quality leads us most of the times to misunderstandings or making mistakes that could be avoided if we had the proper information at the time.
You need to understand communication is part of your job, you are not hired just for one responsibility, all jobs require aside tasks so everyone can be aligned with one another and work together.
In a collaborative environment communication is always a pilar. Having synced teams should be a passive goal of any company, because this increases the productivity, the quality and even the predictability of our deliveries. The more we don’t know, the less predictive we are, because it means we will need more time to research and explore the unknown. One way to improve this is…. ta-raaaaa: through documentation !!
Benefits
So we actually have some benefits of using documentation.
🔎 Less redundant researches
If someone already looked at the same problem as you and it’s somehow documented, then this will boost your way out when finding your solution. If you are a developer, you know that tools like youtube and stackoverflow boost our work a lot.
However, there's knowledge that is pretty tied to your company context that only people that either worked or still work in the same company as you can help you.
👍 People can be better prepared for a meeting
It happens a lot, people coming to a meeting without any clue about what’s it purpose and goal, then you are spending (if not wasting) time of that meeting just give the whole context when it could be something really summed up.
Also, enriches the meeting, because people already put some thought to the issue/topic and probably they already have good questions or inputs to create a dynamic discussion.
📜Historical information
It gives a lot of context for those who weren’t present when decisions were made.
In my opinion, this is the most important advantage of documentation.
We only know History of Mankind because some people in the past thought that could be useful to document those happenings. With these past experiences, we could learn from them to improve our intelligence and avoid making the same mistakes (which we know that don’t happen that much in some matters, unfortunately).
But going back to our techy world. I think it happens a lot, looking at some piece of work in a system and then we ask ourselves “what the hell does this do?”, “why “someone” [git blame 👀] took this approach?” and we are basically falling in a spiral of lack of knowledge mixed with judgement. Well, documentation would probably avoid these kind of situations (whispering like a prayer: and probably being less judgy with our past developers, which we always need to believe they did their best under their own conditions that we are not aware), doesn’t need to be a whole document, sometimes a good description in the commit message could be enough.
😎 🧘♂️It’s asynchronously flexible
Some of the characteristics of documentation is the fact that is an asynchronous task and it’s accessible by everyone in any time (or it should be). This brings flexibility to anyone who’s required to read your document, because you are not blocking anyone’s schedule to receive feedback. They will do it on their own time (with or without a deadline) and you can also work on other things while waiting.
🫂 Avoids meetings through discussion
I am not against meetings, but avoiding them it’s a way of letting people be more productive for their own tasks. Also, a meeting with a lot of people can be costly, time is a unique resource that you can not take back once you use it. Plus, the company is paying you for your time, so bringing a lot of people together for one moment it’s booolldd.
You can use documentation to make a plan or discuss a decision, current tools allow you to comment and reply on it or you can just use threads in your company’s favourite message app. This means, if you can have a whole discussion with decisions as a takeaway about your document, there is a high chance of not needing a meeting, or at least they will be more objective and effective.
👥 Develops collective awareness
Having a knowledge base is always a good resource to keep everyone up to date and synchronised. Specially for new comers.
Misuse of documentation
Well, there are also some issues with documentation, that can easily happen:
- Bad organisation may lead to duplicated information
- If the structure is not clear we might end up having small chunks of information scattered between many documentation systems, which give us a little overhead on finding those when we need it
- A lot of tools may also confuse people that don’t know where to put their information.
- Lack of update will put documents out of date with no big use after a while
Conceptual tips
People often think that you need to write a lot, but you don’t. The purpose of documentation is mainly to inform, plan or ask for feedback about an idea and there are several ways to share information, like text, images, diagrams, audio, video, gifs, tables, lists, etc. So, here are some tips from my experience:
- Guideline: you always need a guideline when you are writing, you want your document to make sense. Like a book, you have sequential happenings that only make sense in that specific order, that helps the reader to construct the idea you want to express and also it's easier to relate and understand your work. You can do it like a journal at first and then filter what you really want to say.
- Structure: This can be something that you can achieve by the end of it, sometimes it's not that clear what kind of structure you want for you document, so it's totally normal if you just build it up along with the writing. Having this helps the reading to be smoother.
- Use templates: some kind of documents are already identify and they usually are suggested by the tool you are using. When you see a pattern on a specific type of document maybe it could help create a template for further documents. This helps for consistency in your knowledge base and also avoids thinking about a good structure next time if you feel that one works.
- Break the monotony: let's face it, people are lazy to read, specially if they are in the middle of their tasks. You need to avoid monotony in your document. Ways of achieving this is by using highlights, other kind of elements in your document such as tables, lists, images, collapsable items, etc., and using a structure will also help a lot to highlight sections!
- Be complete and brief: it seems kinda opposite qualities but what means is that you need to put everything you know with the less words needed. Go straight to the point, avoid using adjectives or adverbs that their only work is just to flourish your text. You don't need that. You are writing a technical document, you just want to inform people.
You know you did it right when nobody has questions
This article is somehow big, so I decided to split this topic into more articles for practical tips. Don’t take this as a commitment from my side, I will be writing when I feel that I want to. Just telling you the kind of experience that I would like to share with you 🙏.
I will try to go through different types of documents that usually a software engineer does, such as: implementation plans (system architecture, APIs, etc), discovery work (Spikes), meeting Notes, github readmes and contributions, team’s space, among others. Covering questions like
- What structure do I follow?
- What kind of elements do I use to highlight my document?
Thank you for reading and please share your thoughts and tips 🙏.
