How to write documentation while developing software

This article represents ways to write agile and lean documentation inside enterprise enviroment, based mostly on developing on .NET platform, but with strife of usage of open and higly agile tools. You may see similar thinking as outlined in this document here 21 and here 22.

Context

What are documents? What is code?

Documents and code are Digital Artifacts. Documentation includes code. Code is documentaion of lowest level. Executable code is executable documentation. Documentation consist of symbols and images. Code consist of symbols. Symbols are organized into higher level structures from low level. There higher level stucture is more long live it is. When ever code becomes long live it obtains documentaion in terms of standards or tests suite or mathematical model. If you write good code you write good documents. If you write bad documents you write bad code. If you write bad code you write bad documents.

Properties

Documentation has similar proprieties as executable code. Both should be:

Searchable

Target audience can find symbols via search engine.

Not searchable documents is not existing documentations and is total waste.

Bad:

Good:

Linked

Each documents links with See also and reference and tags and categories to other docuemtns. Documents are piecemeal. 22

Each documents links level up and down.

Good examples:

Always usable without “ToDo” noise

Evolutionary

Maintainable

Any person can change and generate output of docs, with all revisions traceable.
Change means no need to request rights to edit document, but editing will create fork of document with possibility to do merge changes back in main one.

Bad examples:

**Question oriented **

If somebody going to ask highly anticipated question via private email or chat - write answer beforehand into searchable location. Convert questions and answers in private communication into part of documents.

Targeted
Use views and place views into place people habitat . Think of other people and write for them accordingly 4

Right place

Search place where docs will be most visible.

Write docs into code, instead of docs when possible.2 Put documented interface of code as docs into public.

Write from outer goals to inner specification17 and vice versa18.

Bad examples:

/// <summary>
///  Invokes shortcut
/// </summary>
void Invoke();

Code contains crap shown to all developers in IDE.

And then somewhere into docs in some *.docx put into version control system:

IShortcut.Invoke()    - Method invoked when user presses keyboard combination assigned to this shortcut.

Goal/Intention/Action oriented with What/How/Why separations

2 and more levels of documentation

Source code should not only written self descriptive, but its should be documented yet another time via:

Examples

Simple/Complex or 20/80 separation

Drawing clarified

Executable if possible

Defined retention policy

If docs are just deleted after some time, this is bad.

Bad example:

-Much of docs stored in Issue Tracking system. Issue tracking is not scalable or used in not scalable way. Administrators just delete tail older then 1 year.

Good:

Symbols naming and organization

Good names of classes, methods, namespaces and packages(assemblies) are the easiest means to ensure some documentations presented. Including hierarchical organization and structuring of namings. E.g. MyCompany.MyProduct.MyFeature.MyLayer. 11

Choosing names are kind of TDD. TDD improves code and adds executable documentations. Naming improves code navigation and sustainability of cohesion.

Abbreviations and contractions.

Meanings of these must be searchable or well known by all.

Not used as optimization until other options not evaluated.

See also 10.

Good:

Bad:

Right tools

Right tools are open source or free to deploy. So build servers and developers are free to build and change docs. Who needs doc if reader and user have to buy license to view and change?

Choose right language and tool to put something into mind of reader and help writer. Choose tools any can install and deploy anywhere.