The projectdoc Toolbox supports organizing collections of spaces. Some of these spaces provide general information, some are specific for a product, a project, or a team. Teams may organize their spaces in groups with shared configuration and information.
A basic concept of the projectdoc Toolbox for Confluence is the organization of spaces based on document types. For an author it is important to know, where to store, for a reader, where to find a particular document.
The location of a document is defined by the invariant of a document. This way both, author and reader, are able to determine easily where to look.
Beside the identifier of the creator and the creation time of the document, another invariant property is the type of the document. A report won't become a specification. These properties will not change during the lifetime of the document. Therefore no change to the document would demand to move the document to an alternative location. A document, once created, will be found in the very same location.
For a space there is one location where a specific document should be stored. For a collection of spaces there should also be only one location for a particular document. This is accomplished by allowing only one homepage for each type of document.
This tip shows how you can accomplish this easily with the projectdoc Toolbox.
Readers should be familiar with the different kind of spaces: index space, attachment space, topic space, and workspace. If you would like to read more about these space types, please refer to the tip Using Spaces.
Readers should know what space properties are and how they are used. Please refer to Using Space Properties on how to employ space properties.
Each space may be an island. A team needs a space to collaborate, a corporation needs a space to provide information about a service to their customers. In these use cases everything is self-contained. No references are made between spaces and no space requires labels defined in another space. There is no shared configuration.
By default a space has only one homepage for each doctype. Create a space and you are done.
These single space use cases are typically not very common, if the organization allows to share configuration and information. In these cases, no space is an island!
The projectdoc Toolbox allows configuration on space level using space properties. The configuration of space properties can be delegated to another space – a delegate space. Multiple spaces may share the same delegate space. In fact the projectdoc Toolbox assumes such a default space to have the space key IDX. This is only a default. The delegate spaces for a particular space are defined by the space property Delegate Space.
Commonly used Configuration
Assume that for each space you want the short description of a document to be rendered in front of the property table.
Set the space property Extract Short Description From Metadata Table to the value true in the index space, then every space will automatically use this property and render the short description as instructed.
Sharing configuration is one aspect of a delegate space. The other aspect is the provision of homepages for doctypes. Index spaces define categorizing document types like tags, categories, subjects, and types, including topic type and tag type. These categories help readers to navigate a site. This categories are often shared between spaces. Usually there are some categories that are used in every space.
Resource Types commonly used
If you have resource types like books, article, magazine, there is no need to duplicate this information. In case you put this information in a sitewide index space, every team can reuse this information in their spaces to organized their content.
Since index spaces have typically sitewide access. For a public facing website this information is by default open to anonymous users. You may restrict the access to particular pages, but the users with least privileges have access to the homepage of the space and therefore to the configuration of this space.
To hide sensitive information or information that is not relevant to every space visitor, the information architect may decide to store information with higher access levels in separated spaces. These spaces are called attachment spaces since they are attached to another space. In many cases this central space for attachment spaces is an index space. Attachment spaces are responsible to store information of a given kind. The library stores resources. The address book stores persons and stakeholders.
A library should not store resource types. While a team may not be interested in sitewide resources, they may want to reuse the organization of resources. So consider to store the resource types in an index space.
To attach a space to an index space, the space key is listed by the Delegate Space property.
Reusing some types?
It is a bit cumbersome to ruse only some of the types in a downstream space. One approach is to establish a new homepage for the doctypes and use delegate documents. A delegate document references an existing document and reuses a subset of properties and sections.
This approach is very selective. A team can pick what information they want to use in their work. It also allows the team to have their navigation pages local in their space, not in a sitewide index space.
On the other hand this approach is also requiring much manual work. For each page another page needs to be created and the properties and sections to delegate to need to be selected.
Examples for attachment spaces are address books, glossaries, and libraries. In case you have the use case to provide this information for all your spaces, your sitewide spaces will have a structure similar to the following:
- IDX - the sitewide index space
- ADDR - the sitewide address book
- GLOSS - the sitewide glossary
- LIB - the sitewise library
Assume that the three attachment spaces already exist. To attach these spaces, the configuration for the index space has these lines.
The search space will find documents in all spaces the current user has access to (Search Space Local=@all). The default space closure allows links from the index space point to pages in any spaces the current user has access to (Default Space Closure=search-space). The three attachment spaces need to be configured manually in the index space (Delegate Space=ADDR, GLOSS, LIB).
For this configuration to work properly the attachment spaces and the index space must provide no or exactly one homepage for each doctype.
The current versions of the address book, glossary, and library space blueprints comply with this rule and can be used in combination.
No matter which page in a space of this configuration a user is visiting, when creating a new document, the send-to-homepage function of the page blueprint wizard will find the correct location for this new document.
If a team requires exactly one space, then this space uses the index space with the space key IDX as default delegate. It automatically uses the configuration of the sitewide index space as all homepages of this index space and all its attachment spaces.
The same may be true for a space that is dedicated to a topic (such as performance or security) or a product (such as a Confluence App or a Maven Plugin).
In case a team needs a couple of spaces to meet their collaboration needs, the basic structure of index space and attachment spaces is also a valid solution.
A couple of spaces may use a shared configuration or also require specific attachment spaces. These spaces form a space group. Topic spaces or workspaces with a specific task, such as service management, project management, or risk management, may also be registered as delegate spaces to the space group's index space. Again, the information architect needs to make sure that there is at most one dedicated homepage for a specific doctype.
Instead of an index space with homespaces for various doctypes, a configuration space may be more handy. Required doctype homepages may be added later individually using the homepage blueprint wizard.
Space groups may share the same space label. In this case the search space can be configured to automatically include all spaces of this group in the search space. Every new workspace, tagged with the space label, will be automatically part of the search index of all spaces in this group.
For more information on how to use space labels to define search spaces, please refer to Search Space.
Consider the following relationships of spaces.
Three teams use the sitewide index space with three attachment spaces. Team A decided to have an index space and an attachment space on their own. Team B only needs a configuration space (Index B), and Team C only uses a single topic space for their collaboration results.
When a team member adds a person document and sends it to its homepage, the projectdoc toolbox will find the sitewide address book.
When a member of Team B adds a new document for a book description while working on Workspace 2 (WS2), this document will be send to the sitewide library.
Since Team A has established their own library in their space group, a new resource would be stored in their library space. If the team member decides to move this resource to the sitewide library, this would need to be done manually.
Since Team A does not use a glossary in their space group, a new glossary item is contributed to the sitewide glossary.
The reason to build a hierarchy of spaces is to reuse configurations (in form of space properties), categorization, or information. Configuration and categorization is provided by index spaces, information by attachment spaces.
Based on the index space and attachment spaces pattern, not only the sitewide spaces can be defined, but also spaces groups.
A space group typically uses the sitewide configuration, but also adds configuration and homepages required by its use case.