All notes

Software Documentation


Requirements documentation

If the software is a first release that is later built upon, requirements documentation is very helpful when managing the change of the software and verifying that nothing has been broken in the software when it is modified.

Traditionally, requirements are specified in requirements documents (e.g. using word processing applications and spreadsheet applications). To manage the increased complexity and changing nature of requirements documentation (and software documentation in general), database-centric systems and special-purpose requirements management tools are advocated.

Architecture documentation

A good architecture document is short on details but thick on explanation. It may suggest approaches for lower level design, but leave the actual exploration trade studies to other documents.

A very important part of the design document in enterprise software development is the Database Design Document (DDD).

Technical documentation

It is important for the code documents associated with the source code (which may include README files and API documentation) to be thorough, but not so verbose that it becomes overly time-consuming or difficult to maintain them.

Code documents are often organized into a reference guide style, allowing a programmer to quickly look up an arbitrary function or class.

Literate programming


Introduced by Donald Knuth.

Literate programs are written as an uninterrupted exposition of logic in an ordinary human language, much like the text of an essay, in which macros are included to hide abstractions and traditional source code.

Comparison to well-documented code. Well-documented code or documentation extracted from code follows the structure of the code, with documentation embedded in the code; in literate programming code is embedded in documentation, with the code following the structure of the documentation.

CoffeeScript supports a "literate" mode, which enables programs to be compiled from a source document written in Markdown with indented blocks of code.

Elucidative programming

Elucidative Programming is the result of practical applications of Literate Programming in real programming contexts. The Elucidative paradigm proposes that source code and documentation be stored separately. This paradigm was inspired by the same experimental findings that produced Kelp.

Often, software developers need to be able to create and access information that is not going to be part of the source file itself. Such annotations are usually part of several software development activities, such as code walks and porting, where third party source code is analysed in a functional way.

User documentation

Typically, the user documentation describes each feature of the program, and assists the user in realizing these features. A good user document can also go so far as to provide thorough troubleshooting assistance.

There are three broad ways in which user documentation can be organized:

Documetation, Specification

Why writing them?

As the adage goes, "If you fail to plan, then you plan to fail."

What makes a good doc?

The biggest factor that determines if your design document is good is whether or not it clearly explains your intentions. This presents a problem, however. In order to convey design decisions, you have to consider the audience that you are writing for. Therefore, you need to prepare two versions, one for peer developers, and the other for your managers.

Document templates

Writing for peer developers

The goal of a peer developer design document is to make sure that your ideas are valid and that your approach works with what others are doing.


Writing for a Manager

The goal of a design document for your manager is to make sure that your manager understands what the main entities of the system are, what the benefits are and, most importantly, what the risks are. The document is your chance to show that you understand the requirements and that you have come up with a plan to meet those requirements.

If you have written the peer developer document well, then writing the manager's document is simple, because it is just made up of sections 1, 2 and 4. By dividing the peer developer document up as described previously, the parts which are typically not meaningful to a manager have been contained in a single section of the document which may be removed.