Do you search online for troubleshooting? That’s documentation.

Do you like tutorials in video games, or would you prefer to simply be left alone trying to figure out what each button does? That’s also documentation.

Do you like to see a trailer before watching the movie? That’s documentation right there.

Documentation allows the users / developers to help themselves, and not contact the support (or the developer that initially wrote the code).

Do you enjoy constantly receiving mails such as the following: ‘Hey, I would like to use your library but I have no idea how it works, can we schedule a half an hour call to help me use it’ ?

First of all, you need to figure out if you have to write the documentation for the users (non-technical) or for developers.

Could be that you want to separate these two sides in two different documentation spaces.

The documentation should be comprehensive, and provide feature examples, so developers would know how to use the code properly. At least the most common usecases should be detailed.

Other than that, the documentation should be kept up-to-date, which is usually not the case. To fix that, it should be part of the team’s definition of done.

Why should we write documentation?

Documentation allows stakeholders to have a general view regarding the system, and can reveal problems such as system vulnerabilities. Keeping documentation up to date is great for newcomers, as they would need some design documents as part of the induction training, to be more familiar with the code and the systems.

The high level document should be updated each time an architectural change takes place, while the CDD documents should be updated once every month / every two months.

People forget the code

You will have to read and understand the code written more than 6 months ago.

You may not understand it, and not recognize it even if it was you the one that wrote it.

People want to use your code

If the code is open-source, you want people to be able to use it - because it’s so great, so useful.

But people need to understand what the code does.

If they don’t know what the code does, at a glimpse of an eye, they will not waste more time.

If they don’t know how to install it, they will not use it.

If you want people to use your code, document it!

You want to improve your code

Writing the code is not enough; You have to also make sure it’s the best possible code you could write.

If you put your API and design decisions in a document, you will think about it in a different way, and it could give you ideas about how to improve it.

People who read that documentation can also understand what your intentions were and continue updating your code like you would want.

How to encourage the team to write documents?

While documentation is usually not something we signed up for, the documentation should be kept up to date for the current team members, for newcomers, and for knowledge transfer. Other than that, you can always point out at documentation when people ask you how the system works, so you can go back to coding !

                                            
                                                MyProject
                                                ========

                                                MyProject will solve all your problems.
                                                If you want to use it, here's a code snippet:


                                                    #include "MyProject.hpp"
                                                    MyProject proj;
                                                    proj.solveEverything();

                                                Features / Sections
                                                --------

                                                - Solve everything

                                                Installation
                                                ------------

                                                MyProject do not require any installation, since it is a header-only library.
                                                Just include it in your solution and use it.

                                                Contributions
                                                ----------

                                                - Issue Tracker: insert url here 
                                                - Source Code:   insert url here 

                                                Support
                                                -------

                                                If you encounter any issues, please contact the writer at: MyProject@my_mail_address.ro

                                                License
                                                -------

                                                The project is licensed under the BSD license.
                                            
                                        

The documentation is usually left as ‘nice to have’ in the projects, so in order to assure that it is kept up to date, tasks should be created and properly reviewed. Architectural changes should not be approved without having the HDD update.