Best practices for documenting your project

While documenting a project takes time, you have to understand it doesn’t need to look pretty. It just needs to be functional and updatable – the goal of this is to save a lot of time in the long run. Much more time than you spent on creating it – especially in environments where you get tasked to work on projects you didn’t originally write.

So, to get started, what do you need to document?

Good documentation usually consists of these 8 elements. I’ll list them all and then we’ll explain them in more detail. So, here’s what you’ll need to document:

1. Summary of what the project does and accomplishes
2. Stack the project uses
3. Graph of the app overview
4. Features – what it accomplishes in the current iteration
5. Installation and running
6. Configuration
7. Links to project-related stuff
8. Support – info on who to contact if this documentation still doesn’t help you

Summary

This is the part where you just summarise the project you’re working on. Think if it as this – if someone approaches you just now and asks you “hey, what was that thing you were working on”, write down what you would say to them and that’s your project summary.

Here’s an example of what the SUMMARY part of the documentation could look like.

Stack

What technologies have you used to build the project? You don’t need to mention every single package you pulled with it, but make sure to mention larger things that the whole project is dependent on. Additionally, if you have layers of abstraction, it’s a good thing to point them out here.

Here’s an example of what the STACK part of the documentation could look like.

App Overview

For this part, you can make a graph using a tool like draw.io to better represent how your application works internally. Show everyone how elements are connected. Think of it like this – if you7re starting to work on a project and need to make a change on part X, you’d also want to know which other parts could potentially be affected by your change.

Here’s an example of what the APP OVERVIEW part of the documentation could look like.

Features

In this part, make sure to explain what your app accomplishes in its current iteration, what it enables you to do and what you can do with it. The easiest way to do it is to create a bulleted list of all the info.

Here’s an example of what the FEATURES part of the documentation could look like.

Installation and running

This is part of the documentation where you’ll write down steps you need to take in order to install the app and run it locally (this does not include what configuration you have to setup). Write down those steps here and make a note of any problems someone could encounter while installing/running.

Here’s an example of what the INSTALLATION AND RUNNING part of the documentation could look like.

Configuration

Write down the kind of configuration your app uses, what values you need to setup, does it use environment variables… Config files? Note it all here and briefly explain it.

Here’s an example of what the CONFIGURATION part of the documentation could look like.

Contribute

In this part, write down project-related tools and documents that might help along with this documentation. For example, add the graph used for the app overview so someone else can update it, add API documentation which is documented separately… Also, make sure to include a link to all such sites or services here.

Here’s an example of what the CONTRIBUTE part of the documentation could look like.

Support

This is the last part – this is where you need to include the contact information of the person who can help out if the new person working on the project encounters any problems or needs more information.

And that’s it – that is all the documentation your project needs. Of course, you can expand on this, but I always like to keep documentation as minimal, direct and clear as possible – just the necessary elements.