Organize content by keywords.
- Domain
- Type
- Principles
To impose an architecture on information, the information is typically categorized.
How can we create a sound categorization of our documentation?
Structure
Categorization is the foundation for employing Dynamic Links and creating Views.
Consistency is the key to create a meaningful organization of content. Therefore define a naming convention for categories and stick to it.
Do not use compound labels. If you try to match prefixes or suffixes you should break these labels into multiple smaller ones.
Advantages
- Getting the categories right boosts the findability of information within a documentation. Not only do Dynamic Links depend on this information, information is also searchable by the readers.
Disadvantages
- Categorizing a domain takes time and requires know-how. It is impossible to get it right from the start. So you need to plan an continuous investment to refine the information architecture.
- Keeping track of what categories exist and how to use them may be tricky. You should define each category and use this definition as a collecting space to display all documents that are related. You need to use the categorizes regularly as a team. Categories that are seldom used should be considered to be removed.
Related Practices
The following practices are related to this practice.
- Describe Content
- To make it easier for readers to determine the relevance of a document, there should be short description for each document.
- Dynamic Links
- Build a navigation to related and associated information by the use of document properties and dynamic linking.
- Provide multiple Views
- Provide views on your topic-based documentation.
Resources
For more information regarding this practice please refer to:
- Document Properties Marker Macro
- A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
- Document Properties
- Properties are metadata that can be added to every projectdoc document. If you require a set of metadata for each instance of a document type, you should write your own doctype.
- Category
- Categories allow to set document instance of different doctypes in a hierarchy.
- Tag
- Document the semantics of a tag. May also be used to document Confluence labels.
- Subject
- Subject documents allow to set document instance of different doctypes in a common context.
- Search Tips
- Tips on specifying search queries for Lucene. This also applies to projectdoc's query macros.