Create great documentation as a Software Engineer

The hard truth

You have been working on something for a few days (even a week or more), then you end your tasks, release, relax, and see how your users are using that new cool feature. Now, you want to jump to the next thing and keep having fun (write code).

What you don’t want, is to go and write documentation; and maybe it’s totally fine. It is something boring, we already have the code and all the tests (or I hope so), so people can go and see what it’s done and how it works. You’re a software engineer, you are paid to write great code not to write some text and do some drawing.

I understand the situation, and probably some of you too. I agree on one thing too, do not start writing documentation when you end your “project”. No one has the energy and motivation for doing that and the final result won’t have the quality and details expected of a professional, and we are professionals, right?

What to do instead

Creating software as a professional is much more than just writing code, that is just one part of the whole process. Let’s see how I like to do it, why I like it, and how it all relates to having good practices as a software engineer.

Like most things in the world, having a process will help us to have a good system (which can be improved with time), and that system, will help us to be more professional, more productive and get better results. Mine has these steps:

1. Start the initial documentation.
2. Split things into tasks and create them with all the needed details.
3. Improve doc if needed whit information from the findings to create the tasks.
4. Write test cases to validate the tasks based on the details defined on them.
5. Write code to make the tests work.
6. Improve the documentation after completing each task if needed.
7. Repeat from step 4 until we finish all of the tasks.

The steps

1. Initial documentation

Someone needs to start a document about the problem we want to solve, why we want to solve it, and all the information we believe will be helpful to everyone understanding our duty.

Next step (depending on who is starting the doc), we need to create a first idea (o several if we want to give options) of how to solve the problems, how the solution could be, some small details about it, etc…

Share the document with all the involved people (product, designers, business, developers) and ask for collaboration: add details, make questions, do finding, etc…

Keep doing this until we have an agreed first version. Probably some meetings will be needed to reach this point and do agreements on some points.

All people in the team should be involved in this step.

2–3 Splitting into tasks and updating documentation

With our first version, we need to split the work into tasks that could be accomplished by the team. The better and more complete we create our tasks, the easier it will be to start working on them. With lots of details in the task, any other person can work on that task without any problem, even we can go, do other stuff, and come back after a while and not need to do the same findings again.

Some research will be needed, and some details may change during the findings, we can take that opportunity to update our initial document: add a new diagram, add a link to another document, add a list of values for something, etc.. (anything that can help us in the future, we are working for our future us)

Remember, the more details in the tasks, the better, when you start writing the code, you only will need to think about how to write it, not what to write. You can even go on vacation, come back, and not have to do the same research again.

4–5 Write test cases + code

It’s 2023 when I’m writing this, there is no need to say why we should write tests and how they help us to create better software.

If we have created good tasks, now we can just take one, read it, and create test cases for what the task says our software should do. Just create the cases, write the expectations, and see them fail!.

Now, we can go and write the code. Let’s do it right, write only the code to make the test pass, go to the next test case, see it fail, write the code to make it work, and keep doing this until the work is finished. Do the refactors when needed, and try to write code easy to understand by others (and yourself in the future, like your main priority) and easy to extend.

6 Update the documentation

Have you made any changes to the initial idea? Have you needed to create a new component? Have there been requirements for other equipment? any new dependencies?

This is another good moment to update our documentation with all of those updates. The best approach is to do so when we do the finding, create the new component, etc… Keep doing this until we have completed all the tasks.

Final thoughts

This is my approach to working on projects, sharing responsibility for documentation among all the people on the team. Make the documentation process iterative and avoid that huge amount of documentation creation time, write as you go.

What are the benefits I see?

• The initial version will help us know what to do.
• Well-defined tasks make it easy for us to do whatever it takes to launch the project on time and have test cases ready to write following a TDD approach.
• TDD will help to create only the necessary code, and having tests will help us to use good patterns.
• Avoid that big moment of creating the documentation.
• We’ll end up with some great documentation, very useful to help us in the future: we’ll have a starting point for the next version, a place for other people to look for answers instead of needing us to go and explain it (more time for us to code and avoid interruptions).

Hope this helps someone looking for a way to improve t how they work and feel free to leave comments or thoughts about it. Thank you for reading!