Create a space to work on a given topic. This spaces uses an index space to reuse content.

Background Information

 Show background information ...

Spaces as a Tool

projectdoc assumes that spaces are created frequently. If you want to delve into a new topic, alone or with your team, it is easy to create a new space to copy all the new information into. After you have found all the information you need, you may then decide whether you want to reorganize your current space, move the most relevant information to another space, or archive the working space. This frees your mind from constantly considering where to place a particular information in an area of knowledge you are not yet familiar with.

The Core Add-on provides two kinds of space blueprints for organizing information:

  1. The workspace is designed to store information as you go and be probably archived at the end of your research.
  2. The topic space is designed to keep information that is relevant for you and your team for a longer period of time.

Workspaces are quick-and-easy and will not require any maintenance. Topic spaces are used to organize information for your team so expect to have time to budget to constantly work on this space. The information in topic spaces needs to be kept up-to-date.

Each of our add-ons for projectdoc typically provide one or more space blueprints. These spaces help teams to organize their information quickly. Spaces are designed to be created and ready to work with.

Document Types and Templates

A document type is a logical concept, while a page blueprint is an implementation of a document type in Confluence. We use the terms page blueprint and template often interchangeably and always refer to the implementation that is the basis for creating a new document of a given type. Strictly speaking a page blueprint may contain a collection of templates. Often the collection contains only one template.

The document itself is sometimes called document instance to distinguish it from the document type.

A projectdoc document is a Confluence page with properties and sections. Every projectdoc document is a Confluence page, but it is not required that every Confluence page is a projectdoc document. Confluence pages that are not projectdoc documents are not take into account for searches (for example with the Display Table Macro) by the projectdoc add-on.

projectdoc specifies a simple property called Doctype to define the document type for a document instance. The property is part of the Document Properties Marker Macro that is required on the top of every projectdoc document. In addition to the property, a Confluence page also requires a label with the document type's value.

Doctype Homepages

The documents of a given doctype are organized in homepages. Most of the doctypes have a homepage where the central documents of their types are stored. For each doctype that provides a homepage, the blueprint wizard to create a document provides a checkbox to store the new document as a child of the doctype homepage.

Confluence index pages collect each document created with a given blueprint wizard. Homepages of doctypes reference only those documents that are send to them. There are two kinds of documents that are not stored on the homepage:

  1. documents that are children of a document of the same type (with their root parent being a child of the doctype homepage)
  2. documents that are children of documents a different type

While the first imposes a natural organization of documents and subdocuments (think of roles where the subdocuments refer to specialized roles of their parents), the second usage implies a close relationship between the documents. This close relationship defines that the subdocument has to be deleted when the parent document is deleted. That is: they have the same lifespan.

Homepages may change their structure over time. Some doctypes will only contain a very limited number of documents (e.g. their are typically only a few roles in a small project), but others may have large numbers (e.g. the minutes of meetings may get plenty for larger teams). Therefore expect that the homepage may have subpages to organize documents matching certain criteria. The documents will always be stored as children of the type homepage.

Delegate Space

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. The index space is by definition a default delegate space. But you may declare any space as the delegate space of a given space by adding the space property delegate-space.

Once you have one (or more) delegate space(s) declared, you may remove the homepages of those document types you want to store in the delegate space. If a user selects as the target location of a new page via the "Send to Homepage" parameter, projectdoc automatically selects the homepage from the nearest delegate space.

 

If there is no homepage, the page is stored as a child to the current page.

Search Space

The search space is defined by the search-space space property. It defines for all projectdoc query macros the spaces to search for documents. Per default the search space is the same as the delegate space. You may change that by the use of the space property use-delegate-space-as-search-space.

If you want to list all documents with some criteria of a given doctype, then all documents from the spaces listed as search space that match these criteria are in the result set.

Hands-on Steps

Create a Workspace

Create a workspace that uses the index space as delegate space.

  1. Create a new space based on the Workspace Blueprint
  2. Add the required information and click 'Create'

The new space is created with the homepages defined for the Workspace space.

Use Delegate Space

Workspaces do not have homepages for roles. If you create a new role and send it to the homepage, it will be stored on the delegate's homepage for role documents.

  1. Go to the homepage of the My Workspace you have created in the previous exercise
  2. Create a new page based on the Role blueprint
  3. Add the required information to the wizard and check the 'Send to Homepage' box
  4. Click 'Create'
  5. Click 'Save' at the bottom of the page

The document is stored on the homepage of the index space.

Use Search Space

  1. Go to the homepage of  'My Workspace' you have created in a previous exercise
  2. Edit the page
  3. Add a Display Table Macro
    1. Specify to select all documents with the doctype 'role'.
    2. Save the macro
  4. Save the page

The role 'User' that is stored in the delegate space, is automatically part of the result set.

Next Step

Continue with the next step: Doctypes in Detail

Content