HomeResumeAboutContacts

Effective and efficient documentation for software development. How to write documentation while developing software.

This article represents ways to write agile and lean documentation inside enterprise environment, based mostly on developing on .NET platform, with strife to use open and highly agile tools. You may see similar thinking as outlined in this document here 21 and here 22. Outlined approach does not force specific structure for documentation, but tries provide constraints-facets on documentation making it's production effective and efficient.

Thinking of this approach based on next reasoning:

  • There is no usual paper. You may never print. All things digital. Paper Docs are dead. 22
  • Economically efficient are open, transparent, crowd sourced and continuous processes, or like. Open/transparent/crowd sourced inside Enterprise or/and outside. Other kind of processes are efficient in very rare cases.
  • Documents and code are Digital Artifacts. Documentation includes code. Code is documentation 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. More higher level structure has there more long live it has. When ever code becomes long live it obtains documentation in terms of standards or tests suite or formal 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. Documentation has similar proprieties as executable code.

Constraints-facets

Searchable

Target audience can find symbols via search engine. Not searchable documents is not existing documentations and is total waste.

Bad:

  • Not indexed enterprise Software Control Management with *.docx files in it is waste. E.g. container.docx files committed into SVN not indexed by search engine daily. Or chm or pdf put into location where such documents are not understood by search.

  • Not indexed email communication regarding requirements non shared with large group when it needed. E.g. 3 email threads about the same thing instead 1 and persons who may be interested in information are omitted.

Good:

  • Enterprise collaboration network or wiki.
  • Public internet source repositories and public conversation threads.

Linked

Each documents links with See also and reference and tags and categories to other documents. Documents are piecemeal. 22 Each documents links level up and down. Words can be links also.

Good examples:

  • Wikipedia

  • This book 7. It links to itself, to other books. Exercises also link to creators of exercises. Source of book available in TeX files linked to each other.

Bad examples:

  • Docs authored in long Word documents with all in one with friction full approach to updates and documentation refactoring

  • Most conventional paper oriented books.

  • All books without free online versions because you cannot freely link into them inside your Docs for other to read.

  • Reference documentation leads directly to code. E.g. 19 archive related build system API documentation links directly into git repo code where you read what code does if comment is not enough. Same may be done for closed source but links jump to disassembly.

Always usable without "ToDo" noise

  • No TBD (to be done), no ToDo in text. All such things replaced with one sentence maximally representing what should be unfolded when whole doc is written. Instead of TBD/ToDo phrase which allows guessing intent and makes doc to be always ready.

  • Never DRAFT. Also can be marked DRAFT, but still valuable and valid.1

Evolutionary

  • Good doc starts from few lines of facts which written in 5 minutes but give much more of time saving for others. Then this facts are elaborated, surrounded with definitions, examples, spitted into several docs.

  • 23 and 24 lead to automation

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:

  • Using proprietary software for drawing diagrams when use is not well grounded. This may prevent other people who have no this software from editing and viewing diagrams. May prevent from having Continuous Deployment sever from generating diagram images as part of build process.

  • Some kind of Wiki with friction full way of getting rights for its usage and or modification. Good examples:

  • Free diagramming software which suits needs to describe semantics event if it has not beautiful styles to pretty print.

  • Using Markdown or TeX text files committed into GIT sever with generation of published HTML or PDF as part of build process.

  • Latest C++ standard in GitHub in TeX form.

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

  • QA or Support oriented docs should not different content then Developers, may be overlapping 20% of info, but common parts produced as separate linked documents.

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:

  • Docs are not with code where most value would be provided. E.g. in IShortcut.cs:
/// <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.
  • System.Diagnostics.TraceSource related stuff is good. But it hard to grasp all what/how/why of it without good guiding entering document.

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

  • When I want to do something I search What can be used - list of features and high level aspects.

  • Then I want to do something quick to try via How.

  • Then I rise questions or need clarification in Why.

  • Steps can go any order, I have to be sure for ability to enter from any Doc cause there are several Linked docs different for What/How/Why.

2 and more levels of documentation

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

  • semantically meaningful documentation to code functions

  • static dependency structure revealed by analysis tools for static type languages

  • unit test or integration tests

Examples

  • E.g. script file doing some simple job to automated deployment process is bad without doc header. Each such script file should contain header with description of why and what script does. Such scripts are not target for static dependency analysis or automated testing.

Simple/Complex or 20/80 separation

  • Write down 20 of info about simple things, skip complex things until asked and write down into separate Doc.

Drawing clarified

  • Diagrams may lead to ambiguity not clear without context. Write down exact step by step text what happens on diagram. Restate exactly the same via pretty picture. Not all in one, but several diagrams for different aspects.

Executable if possible

  • Unit tests, unit tests as Koans, Automated Acceptance in Gherkin are preferred to other Docs, because this are not only docs but quality assurance of behavior and APIs.6

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:

  • Collaboration system has archive button, doc is marked archived. Its fetching optimized.

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:

  • Optimize XML not by renaming MySymbol to MS, but via other options. Try to reorganize XML structure. E.g. make MySymbol attribute instead of element or reduce number of times MySymbol is repeated by splitting out addition XML document sub part. Try to use binary serialization.

  • If still need to go with XML and replacing MySymbol with MS, then do this declaratively, e.g. providing explicit dictionary which maps MS <-> MySymbol.

Bad:

  • Contractions not documented.

  • Contractions provided instead of hierarchical context optimization. E.g. FwkWfsProcess instead of Framework.Workflows.Process.

  • Several different contractions. ProcessItemId is not contracted in one place, contracted to ProcItemId in another and to PIID in third one.10

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.

  • mind 9 and concept mapping8

  • collaborative Wiki and ideas discussion

  • version control systems

  • diagramming 20

  • track roles, dependencies and times16

  • web bookmarking and lists

  • zooming presentations 8

  • structure organization of you code to be tool able regarding documentation14

  • document authoring, revision and collaboration tool (e.g. git based text editing with web view)

  • good document authoring language