Notes of course: “Technical Writing: Documentation on Software Projects” by Amber Israelsen

Phases in writing process
Reading Time: 4 minutes

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


Phases in writing process

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.

Be Strong. And Say What You Mean

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

Examples of the proper usage of words warning, caution, note

TIL

always hyphenate

Additional resources:

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:

The User and System 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:

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:

 

If you have found a spelling error, please, notify us by selecting that text and pressing Ctrl+Enter.

Olena Sovyn
Senior Software Engineer (London, UK). I ❤ React, Redux, lodash, React Storybook, and functional programming overall. Always open for learning something new

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Spelling error report

The following text will be sent to our editors: