Go to start of metadata
- Created by Robert Reiner on 09. Apr 2017
Patterns related to team communication and technical documentation.
Patterns of this Domain
| Name | Short Description |
|---|---|
| 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. |
| Categorize | 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. |
| 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. |
| 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. |
| Physical Location | Store information physically only by properties that are invariant. |
| 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. |
| Separate Release Cycles | The product and the documentation of the product should be in different release cycles. |
| Single Point of Access | Users require a single point of access to all information relevant for a project. |
| 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. |
| 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. |
| 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. |
