To investigate on a topic or to create a positioning paper collaboratively with a team, a workspace is a handy tool. Information is collected and arranged and the results may be exported to a PDF to be send to interested stakeholders.
Create a Space
Create a space for collecting information on a given subject.
Select the 'Workspace' type of space:
Workspace vs. Topic Space
While a topic space contains information on a given subject and is updated to reflect the current knowledge on the subject, a workspace is created for a given task. Therefore the information in the workspace is not required to be updated. To the contrary: Once the task is done, the relevant information is extracted, moved to other spaces and the workspace is deleted or archived.
Without the need to update the space, the team may concentrate on the important topics and leave dead-ends and subtopics that have been found to be not relevant as they are.
Add name and description for the space:
The new space looks like this:
Define the Document
The document is the central piece of information collection that will be exported to all interesting parties. These parties may or may not have access to the wiki. Therefore the document needs to be converted into a portable format (such as PDF).
To define this central document create a new page based on the Topic blueprint.
The new document is just a placeholder for the document to create. The document has only a title and a short description and is therefore in the Facade iteration.
Create a section that collects the chapters of your document.
- Add a section with the Section Macro with a title of 'Chapters'
- Add a button to make it easier for your team to create new sections as children to the topic document.
- Add a Display Table Macro to collect documents of type 'section' that are immediate children of the topic document.
The document now looks like this:
Now create sections to define the structure of your document by clicking on the 'New Section' button:
Note that the order of the documents is defined by the Sort Key property. The value for the property are calculated by the Section wizard.
After creating a couple of sections the basic structure may look like this:
Section vs. Topic
Why documents of type Section and not Topics? The title of section has the name of the parent document as suffix. This makes them pretty easy to add without bothering about the uniqueness of the document title. Titles sometimes clash and the separation of title and name of a document helps to keep things smooth and clean.
Currently each document is in the facade state: it has a title and a short description. To track the iteration status of each section document, add the Iteration Property to the table.
- Edit the '
Microservices explained' document - Edit the Display Table Macro in the 'Chapters' section
- Edit the Select Parameter by adding the iteration property
- Save the macro
- Save the page
This is the document with an additional column to display the status of the section documents:
Every document is in facade state. Once the team started to work on the document, it may look like this:
On a glance every team member knows where the team already has contributed to and which chapters have not been worked on.
Document on one Page
The links to the separate chapters may suite your needs to work collaboratively on the document with a team.
To export the document to stakeholders it typically is more appropriate to assemble the different part to a document on a single page.
Use the Transclude Documents Macro to transclude sections from the section documents.
- Add the Transclude Documents Macro and select on section documents that are children to this document
- Select the sections in the child documents you want to transclude; use identifiers and tags
- You may want to exclude the old Chapters section from being printed. If you use ScrollOffice add the ScrollIgnore Macro
The page now looks like this:
For each section the summary is shown. Authors see the boxes around the transcluded content to quickly jump to the section document. The edit icon allows to open the document in a new page for editing.
You are not limited to transclude only one section. If there are multiple section you typically need to add the title of the section and probably move the level of the section to meet include nicely in the parent document.
There are different strategies to define the sections to transclude. The easiest is to list the sections you want or do not want in your document. Here is an example where you want to include every section with the exceptions of references and resources
The transcluded content for this example:
Although the sections are top-level (that is: level 1) in the source document, they are at level 2 in the transcluding document. This is because the Target Level Parameter is set to '*'. projectdoc will calculate the appropriate level for the section in the document (requires Confluence version 5.8+ and the projectdoc Toolbox in version 1.7+).
Alternatively you may add tags to the sections in the section documents and select on those.
Or use a combination of both approaches to select the content for your document.
Export for Stakeholders
The stakeholders interested in the paper may not have privileges to access you wiki or simply need a document they can email to other interested parties. To cope with this requirement the document can be exported to Microsoft Word or PDF.
We recommend to evaluate Scroll Office for this. ScrollOffice is an add-on developed by K15t that makes it very easy to export documents based on corporate Word templates.
If your audience need to compare the changes between to version, you may simply use the version tracking tools provided by Microsoft Word.
It is easy to print the Word document to PDF. The PDF version of the documents are then sent to the external recipients.
