Best Practices for Writing Documentation

Every developer has heard the words “make sure you document your code.” What does this mean exactly? And why go to the trouble of writing about your code instead of just writing good code?

Documentation serves as a communication tool between your present self and your future self. It’s like a save point for those moments when you finally figure out what’s going on and don’t want to lose momentum. After all, you will be using your code in the future, and what you wrote months ago may not be all that clear.

Also, you want people to use your code, right? But who wants to use an undocumented open-source library or contribute to an undocumented project? Almost no one. People need to understand what your code does and how it can be used, and, most importantly, why it might be useful for them.

Finally, documenting code and writing good code are simply two sides of the same coin. A cornerstone of good code is maintainability, and this can only be achieved through understandable, readable documentation.

Now that it’s clear documentation is useful and worth the effort, how do you create proper code documentation? What are the best practices to make sure your documentation is maintainable, understandable, and up-to-date?

In our next UTOPIC0DE Tech Talk, we’ll join with Diana Rodríguez, Python Developer Advocate at Vonage, and Juan Gómez, Google Developer Expert in Firebase & Google Cloud Platform, who will share their own best documentation practices and experiences.

Here’s what you’ll learn:

Join us on Thursday 26th November at 8 PM (CST) and bring questions for us to answer during the live Q&A.


A community that codes. A platform that upskills software developers and matches tech companies with skilled tech talent.