Contents
Intro
This year I will be writing 52 blogs, one for each week of the year. Now I'm a realist, in that holidays and life will get in the way of writing, so my aim is for the number of blogs to be 52 or more, not necessarily one for each calender week.
So that is quite a lot of blogs, you might be asking why.
I've never been a particularly good writer, I guess thats why I've always tended to more numeric courses/roles. But I realise that it is a critical part of any project and life as a whole.
Writing is still the best ways of transferring knowledge between people and generations.
I also think that in tech it is often undervalued, which leads me on to why I'm writing.
Documentation
Documentation is as important as the code of a project. I fundamentally believe that.
If you think back to projects you've enjoyed working on, APIs you've integrated with ease or dependencies you've enjoyed using. I bet they all have good documentation in common.
Likewise if you've had issues using a tool or dependency or API etc, it probably wasn't that well documented, or, like I have on so many occasions, not read the README! 🙈
Documentation can come in many forms:
- READMEs
- Architectural Diagrams
- Background information about what it solves, why it exists
- API Documentation
- Usage Information
- Commit Messages
- Github Issues
- Pull Requests and Review Comments
- Schema Registries
- Types
All these and many more forms of documentation, thread together to provide you with the story, the full picture of a project.
Documentation gives you the who, what, why and how of a project.
Now I'm not saying that every project should have every tiny detail documented, it's very much specific to your circumstances.
For example on my personal projects, there is very little documentation, its just me working on it so I can keep most of it in my head or at least thrown into a simple README.
Whereas at work I like to ensure I've got really thorough READMEs, containing links to any background information about why a project exists, a README with getting started commands, API documentation with example curl requests and responses.
This is because I work as part of a larger and ever growing team and so not everyone will have the same context as I will when I was writing the code, and anyone should be able to pick up the project and understand it practically as well as the person who wrote the code.
I also like to think about future me or successors who will take over the project after me. To ensure that they aren't looking at it thinking what they heck is this, and also partly what was this guy doing! 😂
Understanding what good documentation looks like is really hard, and writing it equally tough.
This is why I'm aiming to write so much this year, to get better with practice! Both reading and writing documentation consistently will help me to produce better documentation, waffle less and make life a bit easier for future me!
I also think writing about a topic can help solidify your understanding of a topic.
Something I've picked up is if documentation is lacking in an area and someone new asks you to explain it, encourage them to document it and then review it afterwards. This not only helps delegate documentation writing, which is often a large task for the more experienced team members. But also helps solidify the new team members understanding, see the situation from fresh eyes and give the new members ownership of a part of the teams work which helps embed them.
I want to just give a shout out to Remark which is a linter for your READMEs which makes so much sense to me. Our code should be of a consistent standard, so why not the READMEs too!
Summary
Documentation is hard. But it is also vital.
I aim to write consistently to help me create better documentation and speed up the process of writing the documentation too! I can already see this happening with how long it takes me to write a blog.
I'd love to hear your thoughts on what good documentation looks like, and example of good docs! Let me know on Twitter.
Top comments (0)