Documentation

Software projects

Documenting a software project is challenging. Even for smaller projects this can be hard. Below a few simple guidelines that help a team writing clear documentation.

Just do it

Most important is to get started. Keep it as short as possible.

Complex code

When you find that documentation takes up a lot of time, most probably the code is too complex. Instead of documenting, simplify the code. Consider refactoring into smaller modules.

Clean code

High quality code is clear and documentation can be short.

Why?

Documentation is about communication. It's a chance to tell others about your code.

Where?

Have your documentation as close to the code as possible. Use markdown files and place them in the same folder as the code. Where needed use markdown links to refer to documents located elsewhere.

When are you done?

Ask someone who does not know the code, preferably in your team, to be the judge of that.

Easily missed

These topics are important but are often left out.

• architectural decissions

• how your code is structured

• non trivial methods and method parameters