...
| Document Properties Marker | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
| Section | ||||||
|---|---|---|---|---|---|---|
| ||||||
| ||||||
If an author knows what information she wants to keep accessible for any stakeholder, found a template to support her with her task, she may still not know where to put it. Every wiki may have a different structure. On the one side this is a strength of wikis. They can evolve and are refactored to a new structure once the problem domain has been better understood. One the other side the individualism makes it hard for teams to create a comprehensible structure to live in - for readers and authors. If documents of similar content are stored at different locations, they are probably hard to find. If an author cannot derive the right location for her document, other stakeholder will probably have a hard time to find it. Projects of similar objectives may be served by similar structures quite well. Software development teams know that the actual location for a file is arbitrary, but it should be the same folder for the same types of files. Furthermore it would be useful if different projects would define the same locations. This way developers who are new to a team will find out easily where to look if they need to find Java or JavaScript source files or the folder where all the sources are compiled to during the build process. This is called a standard directory layout. |
| Section | |||||
|---|---|---|---|---|---|
| How does the projectdoc Toolbox support this?
| ||||
Each template is defined by a doctype that defines the basic structure of every document instance of this type. The structure is a compilation of properties and sections.
In projects documents of the same type tend to be accessed together. Think of documents that describe roles or personas. Or design decisions, meeting minutes, the documentation of aspects of a software architecture. projectdoc defines a default location called homepage for each (with some exceptions that should not bother us here) document type. The homepages are similar to index pages you may already know. There is only a slight difference. While index pages collect every page that has a certain label on it, the documents on the homepage are the most important documents of that type. There may be more documents that are children of these root types. Think of roles! There may be a role document that describes the most generic user of a system. Subdocuments of the User document may be specialized users, like Power User or Admin User. The homepage only has a reference to the User document and allows the reader to drill deeper into the hierarchy step by step. If the user needs an alphanumeric listing of all roles, the index page is still around. But the documents are typically not stored on the index page, but as pages of the homepage or as a descendent of one of the root documents of their type. If you create a space, all homepages are created by default. The space homepage lists references to the homepages (either directly or indirectly).
The 'Topics' link on the space homepage refers to the homepage of the Topic doctype. There is one document instance on this homepage called 'Installation Howto'. On the homepage there are more links to homepages of doctypes (for instance Tours, FAQs, and Glossary). If a team defines a basic structure for their spaces of a given type, new group members, who have worked with other teams on other projects, will have an easier time to get familiar with the domain of a new project. They still have to learn the new domain, but they are already familiar with the structure of the documentation for this domain. |
| Section | ||||
|---|---|---|---|---|
| ||||
Each page wizard for a doctype that supports a homepage, there is a flag to store the document either as a child to the current page (default) or to send it to the homepage for this type.
The screenshot shows the creation of a document for a role named 'User'. The author decided to store the document to the homepage of the 'Role' doctype instead of saving it as a child to the current page. The current page is the page the author viewed when she decided to create a new page by starting the wizard. |
...
