To organize your documentation place documents in a typed repository and add additional views on demand.
A document may be associated with multiple categories and tags. The actual storage location should not be determined by semantics, which can easily change. Moving this documents may be too cumbersome. So a lot of documents may finally end up in the wrong location over time. In addition to that a document is typically categorized in more than one way. You cannot physically store documents in more than one location, even if you want to.
On the other hand, if you add all documents flat to your wiki, localizing them may not be that easy either.
The projectdoc Toolbox recommends to store the documents by their types. For instance there is a repository where all your decisions go and a repository for your meeting minutes. These repositories are called homepages of the doctypes. This approach is pretty safe to changes since the document type imposes a specific structure. Changing a meeting minute into a decision document is therefore rare event.
Links to homepages are typically provided by the space blueprint. Here is an example that links to 10 repositories: with the exception of "Documentation Dashboard" all other links point to a repository for documents of a given type.
Categories, Tags, Subjects, types (like Topic Type or Resource Type), etc. define additional views on the documents. This may make it easier for team members to find documents by browsing.
Example
Suppose you want to provide information about a topic for your team.
Create Page
- Move to your team's space
- Select the Topic Doctype.
- Add information to the wizard and hit "Create"
Note that the checkbox for sending the page to the homepage is checked. The new document will not be stored as a child to the current document, but instead be found as child to the homepage of topic documents (if such a homepage exists).
Homepage Selection
If no homepage exists in this space, but the delegate space provides one, the document will be stored in a different space. Think of resources like a department's library that is shared by multiple teams.
If no homepage can be found in this or any delegate space, the homepage is the current page.
So creating documents and putting them to their natural repository is pretty straight forward.
Edit Page
Here is the top of the new page. For this example only the document properties are relevant, so we do not show the sections (which begin with "Description").
To add additional views on your document you may add information for the following properties:
| Property Name | Doctype |
|---|---|
| Audience | Role |
| Level of Experience | Experience Level |
| Subject | Subject |
| Categories | Category |
| Tags | Tag |
| Type | Topic Type |
| Sponsors | Stakeholder |
The property values may reference a document instance document of a given type. In this case the document instance automatically lists this document as a member of this type. This allows to find the document from different angles in your wiki.
Assume that the team has defined a category called "Security", the topic is relevant for the subject "SuperApp" and the type of the topic is "Tutorial". Then the new topic document will be listed on the Security document of type Category, on the SuperApp document of type Subject and on the Tutorial page of type Topic Type.
Large Numbers
These views are quite handy as long as the lists do not exceed a certain number of documents. If your documentation grows you may need to create a hierarchy of categories (such as Security / Authentication / Apps) or add additional views by using the Display Table Macro (such as querying for tutorials in the security category - WHERE TopicType=Tutorial AND Categories=Security).
