Go to start of metadata
- Created by Robert Reiner, last modified on 10. Jun 2021
List of principles for agile documentation (mostly) derived from software development principles.
Principles
Principles are abstract rules to gain desirable results.
What works for us
Principles need to support a desired quality and be
- clearly worded
- consistent
- no further reducible
We provide references to further resources, helping readers to form their own informed view on this topic. But in the end the borders between values, principles, and practices are based on opinions and experiences and therefore blurry. Readers will come to different conclusions and categorizations.
In the end what matters is simply not the answer to the question "Couldn't is been done differently?" (yes, it can!), but "If we do it that other way, wouldn't it have more positive impact on what we do?".
The lists of principles and practices are meant as a source of inspiration to be adopted and applied to the reader's own way of working. It is not a dogmatic set of rules.
This is by definition a work in progress. If you have a contribution to make, please get in touch!
The following principles help to create desirable qualities or values in documentation. So these principles establish and maintain an effective and efficient communication with the stakeholders of a project.
The following lists group principles by their domain in which they are typically applied. Since our background is software development, you'll find some basic principles associated with this domain, which would also easily be applied to other domains.
Documentation Principles
The following principles are pure documentation principles and have no relative in software design or in the agile or lean mindset.
| Name | Short Description | Supported Values |
|---|---|---|
| Direct Communication Principle | Prefer direct communication between stakeholders. After the meeting brainstorm about which information is relevant to be written down. | |
| 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. | |
| 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. | |
| 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. | Easy to return investment |
| Open Closed Principle | Be open for extension, closed for modification. | |
| Principle of Iteration | Documentation is often created in a process of constant change. Therefore project documentation is never complete. | Easy to return investment |
| 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. | |
| Scaling Principle | Write documents that support transmitting knowledge to many. | Easy to return investment |
| 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. | |
| 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 Responsibility Principle | A document should focus to answer one question. This way documents can be more easily reused and combined. | |
| Stable Dependencies Principle | A document should only reference documents that are not less stable than itself. | Easy to maintain |
| Teamwork | Documentation is created and maintained collaboratively by the whole team. | |
| YAGNI Principle | Assume that an information is not needed to be written down unless proven otherwise. |
Design Principles
The following principles of software design also apply to documentation.
| Name | Short Description | Supported Values |
|---|---|---|
| Direct Communication Principle | Prefer direct communication between stakeholders. After the meeting brainstorm about which information is relevant to be written down. | |
| 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. | |
| 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. | |
| 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. | Easy to return investment |
| Open Closed Principle | Be open for extension, closed for modification. | |
| Principle of Iteration | Documentation is often created in a process of constant change. Therefore project documentation is never complete. | Easy to return investment |
| 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. | |
| Scaling Principle | Write documents that support transmitting knowledge to many. | Easy to return investment |
| 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. | |
| 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 Responsibility Principle | A document should focus to answer one question. This way documents can be more easily reused and combined. | |
| Stable Dependencies Principle | A document should only reference documents that are not less stable than itself. | Easy to maintain |
| Teamwork | Documentation is created and maintained collaboratively by the whole team. | |
| YAGNI Principle | Assume that an information is not needed to be written down unless proven otherwise. |
Agile/Lean Principles
The following agile and lean principles also apply to documentation.
| Name | Short Description | Supported Values |
|---|---|---|
| Direct Communication Principle | Prefer direct communication between stakeholders. After the meeting brainstorm about which information is relevant to be written down. | |
| 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. | |
| 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. | |
| 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. | Easy to return investment |
| Open Closed Principle | Be open for extension, closed for modification. | |
| Principle of Iteration | Documentation is often created in a process of constant change. Therefore project documentation is never complete. | Easy to return investment |
| 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. | |
| Scaling Principle | Write documents that support transmitting knowledge to many. | Easy to return investment |
| 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. | |
| 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 Responsibility Principle | A document should focus to answer one question. This way documents can be more easily reused and combined. | |
| Stable Dependencies Principle | A document should only reference documents that are not less stable than itself. | Easy to maintain |
| Teamwork | Documentation is created and maintained collaboratively by the whole team. | |
| YAGNI Principle | Assume that an information is not needed to be written down unless proven otherwise. |
