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.
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.
Documentation has similar proprieties as executable code. Both should be:
Target audience can find symbols via search engine.
Not searchable documents is not existing documentations and is total waste.
Not indexed enterprise Software Control Management with
*.doc files in it is waste. E.g.
container.doc files commited into SVN not indexed by search engine used daily. Or
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 intrested in infomation are ommmited.
Enterprise collaboration network or wiki.
Public internet source repositories and public conversation threads.
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.
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.
Docs authored in long Word documents with all in one with friction full approach to updates and doc 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
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.
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.
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.
Use views and place views into place people habitat . Think of other people and write for them accordingly 4
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.
/// <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.TraceSourcerelated 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
Simple/Complex or 20/80 separation
Executable if possible
Defined retention policy
If docs are just deleted after some time, this is bad.
-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.
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.
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.
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 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.
collaborative Wiki and ideas discussion
version control systems
track roles, depedencies 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