Eliminate Documentation Effort – Write Just Deltas in Issues

A usual way how to divide information sources through project layers is the following:

  • analysis – textual requirements, UML (use cases, entities, scenarios) or drafts, …sketches, wild cards…
  • design – UML (class model, GUI model) or structured documents/specs
  • task management – used for task tracking, work logging
  • development – source code documented/undocumented
  • user or system documentation – coloured books with screenshots and user-oriented/friendly information about the software product, or pure technical stuff for engineers with some operational information

One of the most important “agile” paradigms is – as little “documentation” as possible through the whole project.

What can be “ignored” to achieve that ?

Every project layer contains some required information:

  • analysis – primary information stuff, requirements or tickets, code design from scratch is really bad idea (can’t be ignored)
  • design – design specifications are derived from analysis artifacts closer to development with implementation-specific details (can’t be ignored – analysis like specs for development is very vague)
  • task management – project- and company-specific tool for capturing who & when supported with design artifacts with some explanations (can’t be ignored – without task management (in any form), we cannot speak about an IT project)
  • development – documented source code is a standard (can’t be ignored, especially for agile development)
  • user and system documentation (if) is needed (can’t be ignored) – there are very few apps that don’t need any help or docs.

This situation looks like unsolvable in order to choose the right way to remove any layer or part of it. Sure, we are not speaking now that all parts have to be done in full detail, for example analysis and modelling by an agile represent more sketching than 12 analysis iterations (it’s not a bad idea, but really expensive one); on the other hand it has to be placed in the project where any project member can find complex information about any project component.
The way is to find penetrations, overlaps or redundancies through all views and artifacts – most important are the project-specific needs and characteristics, which have to be achieved.

The expected result is to find the most simple and smallest project information infrastructure to maintain all recommended project layers and documentation and (suitable) modelling techniques needed for the project.

The solution may be to eliminate design specification with task management and using UML models just as prototyping tool. The main idea is that part of models will be used just as reusable artifacts used when needed on task definition phase, which means that on the prototyping phase a complete specification of the component will be inserted just like an (task management) issue with all stuff together.
Next changes through iterations are coming just like a simple short form text component-related issues without any effort related with documentation or UML model update. It results from the base prototype defined with detailed specs and a chain of small changes and upgrades traceable through a task management system.


  1. write just analytical information into analytical models (strongly recommended – don’t write there any implementation-specific information)
  2. components of task management are your “specification chapters”
  3. use component identifiers in source code in a short or full form
  4. versions are time tracking of the changes
  5. link every issue with version and component(s)
  6. write your Use Cases in a short form, with main and simple scenarios (don’t write scenarios as … “click here, check there” is a wrong way)
  7. forget about writing complex scenarios or test cases (if something is “complex” for you as a project member, it will be overcomplicated for your colleges and overover for the user)
  8. write just critical test cases in detail as test issues
  9. reuse existing issues
  10. define a short and strong specific test issue for implementation issues
  11. verify issue resolving with ad hoc test and code review (more important than only apathetic test issue result black box check)

Recommended issue types for your task management:

  1. new feature (bundle)
  2. task
  3. bug
  4. test task

Most recommended issue properties:

  1. component(s)
  2. recommended version (or iteration)
  3. resolve version (or iteration)
  4. verify version (or iteration)


  1. iteration-derived changes trigger avalanche of changes through all project layers and thousands impacted places (money and time waste)
  2. the same information handled in two or more places (use case -> form specification (the same in other words) -> issue(s) (copy paste from specs) -> code (copy paste from task into source code comments))
  3. low detail implementation-specific change requests trigger analysis update
  4. full system tests after partial changes


  1. effort elimination related to change requests and new features realizations through the design specs and analysis
  2. less or no paperwork (no specs updates, no specs distribution – no frustration)
  3. every feature has its own history (plain specification document can’t capture the whole context)
  4. in every moment transparent status of the project through task management

1. New change request received
Add request, add realization task for the selected component and selected version.
2. Complex information about the component needed (for example by component owner change)
List and read all issues related with the component (there aren’t thousands of them in the biggest most agile projects) … you think it’s very difficult, OK …what redundancy does component owner change have for a project compared to change requests count through iterations? If you have a feature-based project organization, try to imagine that 5 teams will maintain more chapters or model packages in parallel (they have own issues related with components).

3. New test scenarios required
Just write a test task with scenarios and link it with the component.
4. Used test scenarios required
Listing related component test issues from task management and search is recommended. Clone and update for next use.

5. Verification scenarios required
List use case scenarios. If needed, list component-related test tasks and select suitable ones for verification.

6. Change log for some version required
List issues related with recommended version and go through.

7. Change log for any component required
List issues related with recommended component and go through.

There is one failed scenario:
1. complete project specification required (one place for the whole project)

There isn’t …have you ever needed it?

Requirement Engineering, Business Analysis, Agile, Analysis and Design with UML, Java/J2EE, Liferay, Javascript, Embedded C++, MDD, Executable UML, Project Management