ALM Rangers ALM Dogfooding … pondering over documentation – Part 6

Continuing from ALM Rangers ALM Dogfooding, Ruck and the new TLAs – Part 5 I decided to share some learning's and recommendations around documentation, which is part of a Program Manager’s, in fact everyone in the team’s project lifecycle.

Start with the basics

Whether you are documenting a specification, an article, an eBook or guidance for an ALM Ranger project it is recommended to:

Release a (rough) DRAFT early
- Sharing your thoughts and harvesting feedback is more important than polishing the content.
- Create an initial structure covering breadth, not depth. We can always do better (and add details) tomorrow.
- Encourage review as early as possible and “ping” your reviewers … late reviews result in unnecessary and destabilizing churn.
Work as a team
- Our core values state “No one knows everything; as a team we know more”.
- By sharing and working with the team, we create a document that “assimilates” the team’s knowledge and understanding.
- Allows conceptual discussions, prototyping and information gathering to be done by the most appropriate team members.
Limit distractions
- Use formatting and visualizations where it adds value.
- Excessive visualizations, especially screenshots are time consuming and a huge maintenance factor to keep up to date.
Promote “less is better”
- Avoid prose, fluff and decorative content … one of my tenacious challenges
- Reduce redundancy, duplication and irrelevant content.
Include references
- If something is important enough to be included (i.e. it is not fluff), it should be covered in detail or have references to more detail.

Give context! Your document should include an introduction / executive summary

Epics are the foundation of an elevator pitch, which conveys the same message you would share when explaining your adventure to a stranger at the coffee machine.
Include a concise (scrip) summary of the problem context (what is the issue and who is affected) and the justification (why).

Use common templates for a consistent look & feel and encourage a consistent content style. See ALM Rangers – Raising the Quality Bar for Documentation (Part 2) for the ALM Ranger re-styling initiative.