Documentation in the agile projects
“Working software over comprehensive documentation” Agile Manifesto
From scrumalience.org:
- first of all, document things that are not obvious, and can’t be easy to understand
- all documentation should be weight through a value lens
- write documentation when you need it
Plan phase
Purpose.
What is the purpose of this document? If there is no purpose – there is no need in this document.
Purpose of Software Documentation:
- Requirements. Identify what is to be built, and to verify we’re meeting stakeholders’ expectations.
- Design/Architecture. Defines how the system will be constructed, describing critical components and how they fit together.
- Code/Technical. Enables task completion and understanding.
- Test Plans/Test Cases. Define the approach to testing; exposes errors or demonstrate correct behaviour.
- End-User. Enable task completion; provide support and troubleshooting.
Audience.
What does your audience need to know? Omit anything that is not related to the things that need to be included.
Writing tips
There are style guides, that are used for different kinds of documentation. Follow specific style guides if necessary.
Examples of the styles guides:
- The Chicago Manual of Style. (mostly used for history and social science).
- Modern Language Association (MLA). (literature, media, culture publications)
- American Psychological Association (APA). (scientific)
- Others: Microsoft Manual of Style, Associated Press, New York Times.
Clarity
Structural clarity can be increased with usages of:
- abstracts
- introductions
- statement of purpose
- table of contents
- problem statements
- graphs
- tables
- descriptive titles and headings
Stylistic clarity:
- be specific
- be active (in voice)
- be strong and say what you mean
Don’t use words
With passive voice, it might be not clear who exactly performed the action or who needs it do.
Conciseness
- have a clear focus from the start
- eliminate unnecessary words
- use visuals rather than words
**
Stay consistent with what fo these are used in the document.
Use correct words
TIL
Additional resources:
- Elements of Style by William Strunk and E.B. White
- Handbook of Technical Writing by Gerald J. Alred, Charles T. Brusaw and Walter E. Oliu
- A Pocket Style Manual by Diana Hacker and Nancy Sommers.
Layout and design
Deliverables: Requirements
Standish Group CHAOS report – reports how much each year projects in the IT industry were successful, challenged and failed. Also include why the project was challenged or failed.
Good requirement:
- unitary (cohesive). Addresses one and only one thing
- complete. Fully Stated in one place, with no missing information
- consistent. Does not contradict any other requirement; fully consistent with all authoritative external documentation
- atomic. Does not contain conjunctions. “Validate fields A and B” becomes 1) “Validate field A” 2) “Validate field B”
- traceable. Meets all or part of a business need as stated by stakeholders and is authoritatively documented.
- current. Has not been made obsolete by the passage of time
- unambiguous. Concisely stated without use of jargon, acronyms or esoteric verbiage; expresses objective facts; subject to one interpretation
- specify importance. Specifies a level of importance (defined by stakeholders, time or budget)
- verifiable. Implementation can be determined through inspection, demonstration, test or analysis
Requirement perspectives:
Tips for writing clear requirements
DO:
- use terms consistently
- define terms in a glossary
- use active voice
- be careful of boundary values (e.g., “less than or equal to”).
- avoid negation.
Before: Users without an account cannot log into the system.
After: Only users with valid accounts can log into the system.
DON’T:
- design the system (component names, types of controls, database fields)
- use vague terms (user-friendly, efficient, high-performance, approximately, several)
- speculate (usually, often, typical)
- express possibilities (could, ought to, probably)
- ramble
Deliverables: Design/Architecture
Advice for documenting on an Agile Project:
- question the need for the information
- don’t state the obvious
- the goal is to avoid needless refactoring or rehashing a previously made decision
- don’t rely solely on documentation; promote knowledge sharing through other means
(see more: http://agilemodeling.com/essays/agileDocumentation.htm)
The proposed structure for Software Design Document
Additional resources:
- https://ieeexplore.ieee.org/Xplore/home.jsp (and search for “Software Design Description”)
Deliverables: Code Documentation
Comments flags:
- TODO – something you need to do something that was left incomplete.
- HACK – way to signal that you’ve hacked or provided a workaround
- UNDONE – signals code that still needs to be written
Popular Tools for Generating API Documentation
Additional resources:
Deliverables: Test plans and Test Cases
Characteristics of a Good Test Case:
- anyone can execute it
- all necessary details aren’t included
- strong, descriptive title
- consistent naming conventions
- legible and easy to understand
- reusable
Additional resources:
Additional resources for end-user documentation:
- Pluralsight: Writing Process Instructions and Directions
- Technical Writing Process: The simple, five-step guide that anyone can use to create technical documents such as user guides, manuals, and procedures by Kieran Morgan
If you have found a spelling error, please, notify us by selecting that text and pressing Ctrl+Enter.
