- Created by Robert Reiner, last modified on 22. Apr 2019
projectdoc Toolbox
A short introduction on using spaces with the projectdoc Toolbox for Confluence.
- Audience
- Level of Experience
- Type
Spaces are a great tool provided by Confluence to organize information in a wiki. They give purpose to the collection of pages and they contain and make it easy to control access to those pages. Searches can be limited to a number of selected spaces and once a space is no longer needed it may be archieved (or even discarded) with all pages inside.
There is often the question of how to organize pages in spaces. The number of pages stays the same regardless the number of spaces they are distributed over. Too many spaces make it difficult to locate the information, but too few spaces have the same effect.
With the projectdoc Toolbox we developed names for the purpose of spaces. This makes it easier to categorize spaces, organize them, and hopefully hit the right number of spaces for an organization or a given project.
Summary
This short tip introduces the following relations between spaces provided by the projectdoc Toolbox.
- Delegate Space
- Delegate spaces help to organize information that is used by more than one space. Resources may be delegated to other spaces. This includes the definition of space properties and providing homepages for documents of a given type.
- Search Space
- Search spaces extend the search with projectdoc macros for a space per default on a number of other spaces.
Based on these relations, the following types of spaces can be distinguished.
- Index Space
- Delegate space that provides space properties and organizing doctype homepages for other spaces.
- Attachment Space
- Attachment spaces are delegate spaces for entity doctypes.
- Topic Space
- Designed to keep information that is relevant for a given domain and is mandated to be up-to-date.
- Workspace
- Designed to aggregate information that is relevant for a given spike or iteration.
Space Relations
With the projectdoc Toolbox spaces can be put in a delegate and search relation. Both relations allow to create hierarchies of spaces. These hierarchies make spaces easier to handle.
Delegate Space
A delegate space contains space properties and doctype homepages. Spaces related by delegation simply reuse information.
Consider that a number of teams often use the same tags to provide metadata for the documents. Instead of each team documenting these tags on their own, these teams decide to create a delegate space and curate the documentation on the used tags together.
Think of a delegation space as a associated space that contains information on behalf of the delegating space.
A Name List Macro will reference documents in the delegation space hierarchy.
Search Space
For search macros (such as the Display Table Macro) spaces can be connected as search spaces. If information is queried in one space, all its declared search spaces are also automatically included.
A team may have a separate space for each product of a product suite. It then may provide a homespace that provides the entry point to all information on the product suite. On the homepage of this space there is a list of related resources for each product of the suite. Since the spaces are related by the Search Space property, each use of a search macro will automatically include the same spaces in their search context.
Providing Spaces
Based on the delegate space relation, index and attachment spaces provide similar functions.
While the index space is a typical delegate space with space properties and homepages for organizing document types, an attachment space aggregates entities used in multiple spaces. Both space types provide structure for the team's collaborative work on information.
Index Space
Use an index space to define space properties that should be applied to all delegating spaces (that is: a space setting the index space as a Delegate Space).
For instance setting Extract Short Description From Metadata Table to true will render the short description of a document in front of the document properties table. Setting this property in an index space will automatically apply this render rule to all documents of all delegating spaces.
Another example is configuring the metadata sets for HTML metadata in a central index space. The configuration is reused by all delegating spaces.
So any space property of a delegate space is available in a delegating space, if this property is not overridden.
Additional to space properties, index spaces provide home pages for organizing document types such as subjects, categories, or tags. These organization schemes require work to create and are often quiet similiar (at least for the generic types) within an organization. Think of resource types like book or article, module types such as reference or figure, or the expected experience level of the audience, such as beginner or expert.
Attachment Space
Documents describing external resources (such as books, organizations, or people) may be of value for more than one space. These documents should be stored in attachment spaces. Their metadata will make it easy to compile lists of related information.
Resources that describe books or articles may be collected in a single library space. A particular resource may deal with more than one domain. By tagging the resource with the name of the domain, resources can be easily compiled using a search macro as the Display Table Macro. The same goes with organizations and people collected in an address book.
Collaboration Spaces
Topic and workspaces organize information collaboratively developed by a team.
Topic Space
A topic space contains documents that provide the latest information on a domain. This may be a knowledge base on a primary domain for a project or information on a product. It is important that the information is always up-to-date and easy to consume by the readers.
Since documents need to be updated, topic spaces require a lot of time above the initial cost of creating them.
Workspace
A workspace is a collection of records. Like in a journal, new pages are created to contain the information that seems important enough to note for further reference. Like in a journal this information does not need to be updated once new information is discovered that renders previous entries incomplete or wrong.
A workspace is a tool for a short period of time, such as a spike or an iteration in a development cycle. At the end of this period of time the relevant information is copied to topic spaces and all interims states of knowledge are discarded. This supports teams to aggregate information quickly and decide at a later point - where more knowledge is collected an processed - how to organize it.
A workspace may also be used for a long period of time. A personal or team journal may continously log events that are important to preserve at a point in time. Personal spaces are considered workspaces by this definition.
Resources
- projectdoc Spaces
- projectdoc introduces structure on a Confluence space. It adds the concept of homepages for document types.
- Spaces Introduction
- Provides a gentle introduction to the concept of spaces using projectdoc.
- projectdoc Space Relationships
- projectdoc allows to group spaces and to set them in two kinds of relationships: delegate and search.
- Space Properties
- Lists the configuration options at space level.
- Glossary
- Terms used in and defined for projectdoc.
- Agile Documentation
- Information on agile documentation: from values to principles and practices. A set of actionable tools for team communication.
- Frequency of Change
- Consider content by the frequency of change. Group content in information sets that change in the same frequency. The most important category for changes is the record, which implies no change.
- Developer Diaries
- A short introduction to developer diaries.
