You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 4
Next »
A description of a given topic. A topic may describing or explaining a concept, a task to accomplish or a reference. There are a couple of topic types that set the expectations for the reader. Instances of the topic doctype usually have independent lifetimes from any referencing documents.
Description
A topic is a document that provides specific information. While topics share a basic structure, they are quite different in nature.
The topic type defines the type of content to be expected in the document. Typical topic types are
Fragments, like examples, boxes, or other modular snippets designed for reuse are also topic documents.
Properties
The document type topic provides the following properties:
Level of Experience
Help for the reader to estimate, if her knowledge matches the required level of experience with the subject of this document.
Expected Duration
The duration expected by the author of the document, readers require to work through the topic document.
Type
The topic type of the document. This helps the user to estimate, which kind of information on the topic will be expected.
Sections
Prerequisites
Expected knowledge of the user or a list of documents suggested to be read before this one.
Subordinate Topics
A larger topic may be broken down into individual subtopics.
Other than Section documents, subtopics may have an independent lifespan and may recognized as relevant standing on their own. If the subtopics do not satisfy this requirement, you may choose to break the topics into sections instead of subtopics.
Notes
These are internal notes that are usually not exported and only visible to team members with write access.
But this is not a safe place to store sensible information. It is just a convenience for the reader to not be bothered with notes stored here for the authors for later use. The security level is about suppressing the representation by a CSS style. Therefore consider this as a convenience for the reader, not as a security tool.
References
For a document the references section contains pointers to resources that prove the statements of the document.
Often these proofs are not easily distinguishable from further information. In this case you may want to skip the reference section in favour for the resource list.
Resources
The resources section provides references to further information to the topic of the document.
This may be information on the internet provided by the resource or information in the team's information systems. Anything the reader of the resource might want to know, may be listed here.
