You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
Version 1
Next »
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.
A team needs to create a documentation collaboratively. Readers of this documentation need to think that the documentation has been written by one person. This makes it easier to understand the information.
How can we reduce the work for knowledge workers to provide information for the documentation?
Structure
Use document templates to define a basic structure for all documents of a given type. Readers will have an easier job on finding and learning about the information in a document.
Use space templates to organize documents within you documentation. This will lead to a similar structure for all spaces a reader is visiting. Readers will have a much easier time to find information in spaces whose structure is familiar.
Advantages
- Documents are similar in structure and therefore easier to digest by readers
- Authors do not need to reinvent the wheel and can build upon lessons learned by the team or organization
Disadvantages
- Beware of becoming a template zombie! Templates are tools to support authors with a proven structure that served the team well in the past. Authors need to be encouraged to focus on the information they want to deliver by adjusting the structure and even the formatting as they seem fit.
- Templates need to be created and continuously adjusted to the changing requirements of the team.
Resources
| Name |
Short Description |
| 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. |
| 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 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. |
