Date: Fri, 29 Mar 2024 02:30:48 +0100 (CET) Message-ID: <32174617.17595.1711675848027@09e9d69a2016> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_17594_1879291281.1711675848027" ------=_Part_17594_1879291281.1711675848027 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
List of principles for ag= ile documentation (mostly) derived from software development principles.
Principles are abstract rules to gain desirable results.
What works for us
Principles need to support a desired quality and be
We provide references to further resources, helping readers to form thei= r own informed view on this topic. But in the end the borders between value= s, principles, and practices are based on opinions and experiences and ther= efore blurry. Readers will come to different conclusions and categorization= s.
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 w= ay, wouldn't it have more positive impact on what we do?".
The lists of principles and practices are meant as a source of inspirati= on 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 th= ese principles establish and maintain an effective and efficient communicat= ion with the stakeholders of a project.
Actionable Practices
In order to make principles more actionable, teams develop = practices.<= /p>
The following lists group principles by their domain in which they= are typically applied. Since our background is software development, you'l= l find some basic principles associated with this domain, which would also = easily be applied to other domains.
The following principles are pure documentation principles and have no r= elative 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 brainst=
orm about which information is relevant to be written down.
|
|
DRY Principle |
Redundant information is hard to maintain, keeping it in-sync. Therefore st=
rive for reducing redundancy by defining one authoritative location f=
or each piece of information.
|
|
KISS Principle |
Keep your documentation simple. Assume that authors have relevant informati=
on for the project in their mind, but not necessarily the skills and resour=
ces 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 w=
ithout notice.
|
|
L= ong-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.
|
|
Pr= inciple of Iteration |
Documentation is often created in a process of constant change. Therefore p=
roject documentation is never complete.
|
Easy to return investment |
Principle of least Aston= ishment |
Documentation should appear to the reader as being written by one single pe=
rson. 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 th=
e concerns regarding the formatting and - as far as possible - the structur=
e from the content. Whenever there are different aspects, consider if handl=
ing them independently would make things easier.
|
|
Single Responsibility Principle |
A document should focus to answer one question. This way documents can be m=
ore easily reused and combined.
|
|
Stable Depende= ncies Principle |
A document should only reference documents that are not less stable than it=
self.
|
Easy to maintain |
Teamwork<= /a> |
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 o=
therwise.
|
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 brainst=
orm about which information is relevant to be written down.
|
|
DRY Principle |
Redundant information is hard to maintain, keeping it in-sync. Therefore st=
rive for reducing redundancy by defining one authoritative location f=
or each piece of information.
|
|
KISS Principle |
Keep your documentation simple. Assume that authors have relevant informati=
on for the project in their mind, but not necessarily the skills and resour=
ces 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 w=
ithout notice.
|
|
L= ong-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.
|
|
Pr= inciple of Iteration |
Documentation is often created in a process of constant change. Therefore p=
roject documentation is never complete.
|
Easy to return investment |
Principle of least Aston= ishment |
Documentation should appear to the reader as being written by one single pe=
rson. 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 th=
e concerns regarding the formatting and - as far as possible - the structur=
e from the content. Whenever there are different aspects, consider if handl=
ing them independently would make things easier.
|
|
Single Responsibility Principle |
A document should focus to answer one question. This way documents can be m=
ore easily reused and combined.
|
|
Stable Depende= ncies Principle |
A document should only reference documents that are not less stable than it=
self.
|
Easy to maintain |
Teamwork<= /a> |
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 o=
therwise.
|
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 brainst=
orm about which information is relevant to be written down.
|
|
DRY Principle |
Redundant information is hard to maintain, keeping it in-sync. Therefore st=
rive for reducing redundancy by defining one authoritative location f=
or each piece of information.
|
|
KISS Principle |
Keep your documentation simple. Assume that authors have relevant informati=
on for the project in their mind, but not necessarily the skills and resour=
ces 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 w=
ithout notice.
|
|
L= ong-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.
|
|
Pr= inciple of Iteration |
Documentation is often created in a process of constant change. Therefore p=
roject documentation is never complete.
|
Easy to return investment |
Principle of least Aston= ishment |
Documentation should appear to the reader as being written by one single pe=
rson. 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 th=
e concerns regarding the formatting and - as far as possible - the structur=
e from the content. Whenever there are different aspects, consider if handl=
ing them independently would make things easier.
|
|
Single Responsibility Principle |
A document should focus to answer one question. This way documents can be m=
ore easily reused and combined.
|
|
Stable Depende= ncies Principle |
A document should only reference documents that are not less stable than it=
self.
|
Easy to maintain |
Teamwork<= /a> |
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 o=
therwise.
|
More on documentation values and documentation practices: