List of Practices

The practices follow the documentation principles to establish and maintain an effective communication.

Practices typically have areas where they are best applied, have pros and cons. Therefore they are presented in a pattern form.

#	Name	Short Description	Principles
1	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.	YAGNI Principle, KISS Principle, Teamwork
2	Categorize	Organize content by keywords.	Principle of least Astonishment, Open Closed Principle
3	Describe Content	To make it easier for readers to determine the relevance of a document, there should be short description for each document.	Principle of least Astonishment, Self Documentation Principle
4	Document State	To set the expectation right it is useful to communicate the state of each document to the collaborating authors and the readers.	Teamwork, Principle of Iteration, Principle of least Astonishment
5	Dynamic Links	Build a navigation to related and associated information by the use of document properties and dynamic linking.	Open Closed Principle
6	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.	Principle of least Astonishment, KISS Principle, Teamwork
7	Employ Delegate Documents	Delegate documents make it easier to reuse content from existing documents as a whole.	DRY Principle, Teamwork
8	Employ Impersonator Documents	Impersonator documents make it easier to reuse structure with different content.	DRY Principle
9	Favor flat Hierarchies	Organize information physically in flat hierarchies. Add views to put these documents in different contexts.	Stable Dependencies Principle
10	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.	Separation of Concerns
11	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.	Stable Dependencies Principle, Law of Demeter, Separation of Concerns
12	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, YAGNI Principle, Teamwork, Separation of Concerns
13	Know your Mission	Use charters to define the purpose and benefit of each document. State the expectation of the stakeholders involved.	Principle of least Astonishment, YAGNI Principle, KISS Principle, Teamwork
14	Last responsible Moment	Defer a decision to the last responsible moment is also a risk-reducing technique for writing documentation.	YAGNI Principle
15	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.	Principle of least Astonishment, DRY Principle
16	Make Reader feel Home	Communicate in a way expected by the reader.	Principle of least Astonishment
17	No Noise	Do not render text to the reader that has no information value.	Principle of least Astonishment, KISS Principle, YAGNI Principle
18	Physical Location	Store information physically only by properties that are invariant.	Stable Dependencies Principle, Separation of Concerns
19	Privacy, please	Separate documents and records with different level of privacy.	Separation of Concerns
20	Provide multiple Views	Provide views on your topic-based documentation.	DRY Principle
21	Separate Release Cycles	The product and the documentation of the product should be in different release cycles.	Separation of Concerns, Principle of Iteration
22	Single Point of Access	Users require a single point of access to all information relevant for a project.	Principle of least Astonishment
23	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.	Single Responsibility Principle, DRY Principle, Separation of Concerns, Self Documentation Principle
24	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.	DRY Principle, Principle of least Astonishment
25	Tell me, I'll summarize	A simple technique to enforce common understanding and knowledge distribution on important topics.	Teamwork, Direct Communication Principle
26	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.	Principle of least Astonishment, KISS Principle, Teamwork
27	Use your Tools	Experts need the freedom to employ the set of tools they work most effectively and efficiently.	Teamwork, Separation of Concerns
28	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.	Stable Dependencies Principle
29	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.	Scaling Principle, Long-term Relevance Principle

Incubator

The following practices are still under development.

#	Name	Short Description	Principles
1	Employ Mapping Documents	Mapping documents support adding information to the association of two (or more) documents.	DRY Principle, Single Responsibility Principle

Resources

More on documentation values and documentation principles:

Values: Values represent characteristics or qualities of documentation that are important to readers, writers, and sponsors.
Principles: List of principles for agile documentation (mostly) derived from software development principles.