List of Patterns

List of all agile documentation patterns.

Agile Documentation
A document is considered to follow the agile principle if it is valuable, essential, and created or updated just-in-time. A documentation is created and maintained in an agile way, if all its documents follow this practice.
Organize content by keywords.
Describe Content
To make it easier for readers to determine the relevance of a document, there should be short description for each document.
Direct Communication Principle
Prefer direct communication between stakeholders. After the meeting brainstorm about which information is relevant to be written down.
Document State
To set the expectation right it is useful to communicate the state of each document to the collaborating authors and the readers.
DRY Principle
Redundant information is hard to maintain, keeping it in-sync. Therefore strive for reducing redundancy by defining one authoritative location for each piece of information.
Dynamic Links
Build a navigation to related and associated information by the use of document properties and dynamic linking.
Employ a Style Guide
All publishing organizations define a style guide for their published information. Such a guide supports teams to write in a similar tone, making it easier for readers to digest the information.
Employ Delegate Documents
Delegate documents make it easier to reuse content from existing documents as a whole.
Employ Impersonator Documents
Impersonator documents make it easier to reuse structure with different content.
Employ Mapping Documents
Mapping documents support adding information to the association of two (or more) documents.
Favor flat Hierarchies
Organize information physically in flat hierarchies. Add views to put these documents in different contexts.
Focus on Content
Make it easy for knowledge workers to focus on content and remove the need to define the document structure and formatting on a ad-hoc basis.
Frequency of Change
Consider content by the frequency of change. Group content in information sets that change in the same frequency. The most important category for changes is the record, which implies no change.
Keep a Journal
In order to take personal notes on one's own work and to reflect upon what has to be done or has been done, keep a journal. The information in the journal should be shareable at least with all team members.
KISS Principle
Keep your documentation simple. Assume that authors have relevant information for the project in their mind, but not necessarily the skills and resources to communicate it. Therefore make it very simply and joyful for them to share their expertise.
Know your Mission
Use charters to define the purpose and benefit of each document. State the expectation of the stakeholders involved.
Last responsible Moment
Defer a decision to the last responsible moment is also a risk-reducing technique for writing documentation.
Law of Demeter
Documents should not reference details in other documents that may change without notice.
Long-term Relevance Principle
Prefer to invest more in preserving information with long-term relevance to the stakeholders.
Maintain a Glossary
To enforce a common understanding of the domain, a glossary should define the terms important for the project. This also supports the ubiquitous language and makes sure nobody is left behind.
Make Reader feel Home
Communicate in a way expected by the reader.
No Noise
Do not render text to the reader that has no information value.
Open Closed Principle
Be open for extension, closed for modification.
Physical Location
Store information physically only by properties that are invariant.
Principle of Iteration
Documentation is often created in a process of constant change. Therefore project documentation is never complete.
Principle of least Astonishment
Documentation should appear to the reader as being written by one single person. Uniformity reduces the chance of astonishment. The principles applies to all areas of documentation, including style and organization.
Privacy, please
Separate documents and records with different level of privacy.
Provide multiple Views
Provide views on your topic-based documentation.
Scaling Principle
Write documents that support transmitting knowledge to many.
Self Documentation Principle
There should either be no need for additional documentation for an artifact or that documentation should be as close as possible to the artifact. This make it more probable that the documentation changes with the artifact and therefore keeps up-to-date.
Separate Release Cycles
The product and the documentation of the product should be in different release cycles.
Separation of Concerns
Reduce the amount of documents with overlapping information. Also divide the concerns regarding the formatting and - as far as possible - the structure from the content. Whenever there are different aspects, consider if handling them independently would make things easier.
Single Point of Access
Users require a single point of access to all information relevant for a project.
Single Responsibility Principle
A document should focus to answer one question. This way documents can be more easily reused and combined.
Single Sourcing
Reduce redundancy by having one source of truth for each information. This way the written information is more easily reusable in other documents and - which is even more important - it is referenceable. Single sourcing demands automation.
Stable Dependencies Principle
A document should only reference documents that are not less stable than itself.
Standard Layout
A standard layout makes it easier for new members of a team to find information. A standard layout is project independent and is typically defined by an organisation.
Documentation is created and maintained collaboratively by the whole team.
Tell me, I'll summarize
A simple technique to enforce common understanding and knowledge distribution on important topics.
Use Templates
Define a basic structure for all artifacts of a given type. Readers will have an easier job on finding and learning about the information in your documentation.
Use your Tools
Experts need the freedom to employ the set of tools they work most effectively and efficiently.
Welded Lifespan
If documents are added as children to a document, these documents share the lifespan of the parent. If the parent is removed, so are the children.
Write to the many
Invest in the creation of a document relative to the amount of its readers and the estimated time they will save searching for the information. Also take into account that a clear text reduces the risk of misunderstanding.
YAGNI Principle
Assume that an information is not needed to be written down unless proven otherwise.

Need more Info?

More information on doctype:

Related Information

Related information in your wiki:

  • No labels