- Created by Robert Reiner, last modified on 29. Apr 2017
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.
- Domain
- Type
- Values
Separate a documentation into distinct sections such that each section addresses a separate concern. A concern is a set of related information.
Let me try to explain to you, what to my taste is characteristic for all intelligent thinking. It is, that one is willing to study in depth an aspect of one's subject matter in isolation for the sake of its own consistency, all the time knowing that one is occupying oneself only with one of the aspects. We know that a program must be correct and we can study it from that viewpoint only; we also know that it should be efficient and we can study its efficiency on another day, so to speak. In another mood we may ask ourselves whether, and if so: why, the program is desirable. But nothing is gained —on the contrary!— by tackling these various aspects simultaneously. It is what I sometimes have called "the separation of concerns", which, even if not perfectly possible, is yet the only available technique for effective ordering of one's thoughts, that I know of. This is what I mean by "focussing one's attention upon some aspect": it does not mean ignoring the other aspects, it is just doing justice to the fact that from this aspect's point of view, the other is irrelevant. It is being one- and multiple-track minded simultaneously.
Edsger W.Dijkstra. On the role of scientific thought. 1974
Example
Each document is based on three components: contents, structure, format.
These there concerns must all support the topic described in the document, but may require a different expertise. Typically not each team member is good at all of these aspects equally. Therefore there should be tools to support the team member to concentrate on one at a time. For instance a blueprint and style sheets take care of the basic structure and the formatting styles. Relying on these tools, the author can concentrate on the content to deliver the information. The structure and format may none-the-less be fine-tuned by the author to further support the information.
Related Practices
The following practices are related to this principle.
- 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.
- Physical Location
- Store information physically only by properties that are invariant.
- Privacy, please
- Separate documents and records with different level of privacy.
- Separate Release Cycles
- The product and the documentation of the product should be in different release cycles.
- 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.
- Use your Tools
- Experts need the freedom to employ the set of tools they work most effectively and efficiently.
Related Principles
The following principles are related to this principle.
- 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.
- Open Closed Principle
- Be open for extension, closed for modification.
- 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.
- 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.
- 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.
- YAGNI Principle
- Assume that an information is not needed to be written down unless proven otherwise.
References
More information on this principle.
- Separation Of Concerns
The principle described as a pattern on wiki.c2.com.
- Separation of concerns
The principle described on Wikipedia. The description above is derived from sentences this article (replacing the focus from programming to documenting).
- On the role of scientific thought
- Article by Edsger W.Dijkstra where he explains the term 'separation of concerns' by 'focussing one's attention upon some aspect'.
