Most of your documentation shouldn't describe the implementation (i.e. the C++).

IMO the most important documentation is:

What does the software do, and/or why?
How do you build the software?
How do you test the software?

Other types of document are listed here: What Types of Documents Should You Create?

When I describe the implementation, I tend to describe (or "document") only its high-level structure: for example, if it's designed or built as several components (high-level "components" such as "executables" or "libraries" or "packages" or "layers"), then why, and what are they? Which are the "public" (public, published, user-facing) interfaces? Which are the internal interfaces (between packages)? I'd tend not to document the relatively private interfaces within each package (i.e. the code itself should be sufficient documentation of that).

Therefore most documentation isn't at the code-level (e.g. Doxygen), instead it's text intended for readers (e.g. HTML or Word or Markdown -- or emails).

Another form of "documentation", of the public APIs, are the automated test cases that you write to regression-test the software by driving (using, exercising) those APIs -- these are code rather than text -- and any assumptions about the API (how to use it and exactly what results to expect), and/or examples of how to use it, are encoded in the test cases.

A useful type of detailed documentation is the "functional specification" -- i.e., "What are the requirements, what is the software meant to do?"

This type of documentation is potentially useful to many different audiences (and may be written, when the software is specified but before the software is coded):

Marketing and customers read it to know what (functionality) they're going to be getting
Technical writers read it to understand what (functionality) they'll document
The product manager reads it to verify you've understand what (functionality) they're specifying
Testers read it so that they know what the functionality is supposed to be (so that they can test whether it is that and/or does that)
Developers read it so that they know:

What (new functionality) they are supposed to implement
What (specified functionality) they were supposed to implement
What (old functionality) was implemented when that needs changing somehow, or reimplementing, in future.

Writing documentation may be unpopular, though, e.g. it's associated with BDUF, and too much process ... someone might prefer that instead of documentation, the various specs were agreed and kept in mind by the project stake-holders.

But needs vary -- sometimes there are industry or business requirements, which might dictate having auditable documentation and development process (see e.g. ISO 9001) -- or a business might want documentation to help train new developers -- and sometimes (e.g. if you're publishing an API rather than only publishing a UI) there's need to document your public APIs well, because it's documentation that's required and expected by customers and users (i.e. external developers).

So the optimal quantity and type of documentation varies: depending e.g. on the size of the team, duration of the project -- the type of project -- and so on. If it's all just you and one project manager (and no industry regulations or corporate development process to comply with), you might have almost no documentation, and instead only e.g. phone calls to agree on what to implement next.

---

(0)

Login to post a comment!