Homepages to store Documents

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).

Here is an example from a space created by a projectdoc space blueprint.

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.

Default Target to store Documents

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.

Delegate Spaces and Homepages

Some documents are relevant to more than one space. If you have a large project with multiple large components you may want to have a space for each component you describe. Each component may share the same roles and topic types. So there is no need to have them copied around spaces. Instead have them stored in a collaboratively used delegate space.

There may be more than one delegate space. Delegates spaces are specified in an ordered list.

Whenever an author sends a document to its doctype homepage, the document is stored to the immediate homespace page found in the delegate space hierarchy. Assume for instance that the current space has a delegate space with a homepage for roles, but has itself no such homepage. If a document of type 'Role' is sent to its homepage, then it will be stored on the role's homepage on the delegate space.