- Created by Robert Reiner, last modified on 17. Aug 2018
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 5 Next »
projectdoc Toolbox
Short introduction on using data tables or using views on data.
- Type
- Level of Experience
This short introduction shows how a table of data can be transformed into a web of documents on your Confluence wiki using the projectdoc Toolbox.
Table of Data
Suppose you need to list some data about your team mates: Tina, Mike, and John.
You create a new page and put the currently relevant information in a table like this:
Name | Phone | |
---|---|---|
Tina | christina@example.com | -123 |
Mike | michael@example.com | -204 |
John | john@example.com | -451 |
Next you realize that the skype ID and mobile phone number are also relevant.
Name | Phone | Mobile | skype | |
---|---|---|---|---|
Tina | christina@example.com | -123 | +01 123 23451 | tina.m |
Mike | michael@example.com | -204 | +01 123 23671 | super.mickey |
John | john@example.com | -451 | +01 123 24656 | delibunknown |
Next you learn that this information is relevant to freelancers that are also members of your team. So you decide to state the full phone number and the full name.
Name | Phone | Mobile | skype | |
---|---|---|---|---|
Christina Meyer | christina@example.com | 098 321-123 | +01 123 23451 | tina.m |
Michael Suba | michael@example.com | 098 321-204 | +01 123 23671 | super.mickey |
John Doely | john@example.com | 098 321-451 | +01 123 24656 | mycorporationme |
Now you can add more information for a team member by adding additional columns and more team members by adding additional lines.
This is quick and easy and is often fair enough.
Additional Requirements
There are usually some use cases that you encounter dealing with this kind of information.
- Selecting on Information
- Not all team members may need to be on the table for some users.
- Not all users are interested or should have access to all information about a team member.
- Users may want different views on information such as internal staff has access to the extension phone number while external freelancers have the full number.
- Referencing Information
- You can reference the whole address book of team members
- Users may want to pass a link to a team member or use it in their documentation (e.g. in meeting minutes)
- Adding more Information
- Notes on the team member, e.g. special interests or availability for the project
- Fields of expertise
- History of projects
- References to topics in the wiki the team member is one of the authors
Handling these Requirements
So what are the options to handle these requirements with the tabular approach and what is an alternative?
Selecting on Information
Selecting on information in a table can be done by filtering. Filters may reduce the amount of columns and the amount of lines.
Another way to solve the problem would be to create a page in the wiki dedicated to only one person.
Name | Christina Meyer |
---|---|
christina@example.com | |
Phone | 098 321-123 |
Mobile | +01 123 23451 |
skype | tina.m |
Fields of expertise
- ...
- ...
- ...
History of projects
- ...
- ...
- ...
- ...
Name | Michael Suba |
---|---|
michael@example.com | |
Phone | 098 321-204 |
Mobile | +01 123 23671 |
skype | super.mickey |
Fields of expertise
- ...
- ...
- ...
History of projects
- ...
- ...
- ...
Name | John Doely |
---|---|
john@example.com | |
Phone | 098 321-451 |
Mobile | +01 123 24656 |
skype | mycorporationme |
Fields of expertise
- ...
- ...
- ...
- ...
History of projects
- ...
- ...
The page can be based on a blueprint to make it easier to add new members and provide the information that is most relevant to the team. Information that should only be visible to team members in certain roles could be added on separate pages. The access to these pages is restricted by the wikis access control and are transcluded on the public page. Therefore the transclusion will only happen if the user has sufficient access to the restricted information.
You can add information in different formats. For instance the telephone number in form of its extension and in full format. You may also define different type of team members where different types of information is relevant.
To automtically render the information of all team members in tabular form, use the Display Table Macro. This macro allows you to query for team members with certain properties and select to show only the personal information that is relevant to your use case. That is you have the information of team members in one place and then have multiple views on this information by using the Display Table Macro.
Referencing Information
To reference a single member you would need to reference a single line in the table.
If you have each team member on a separate page, the URL to that page references the team member. Via this URL all information about the team member that is relevant to the team is accessible. This URL can be easily added to other documents to create a web of information.
Adding more Information
In tabular form it is often unwieldly to have short information like a name in the same line as a list of special interestes or other multi-line notes.
If the information for a team member is on a separate page, any information can be added. The projectdoc Toolbox distinguishes between Document Properties, which are typical single line and used to filter on team members for a search result and Document Sections which comprise multiple blocks like paragraphs or tables. Since each view selects on information, the information can be rendered in the most appropriate layout.
Having defined fields of expertise on could also collect names of team members who are provicient in that field. That is by clicking on an expertise on a team member page, the user would have access to a list of team members that also have knowledge in that area.
If you document projects and link to the people who are part of the team, a history of projects can be automaticall rendered on the team member pages. The same is true for topics the team members are authors of if they are mentioned as as authors on the topic page.
Conclusion
Having each information on a separate page makes it referencable. You can add any number of views on this information and some information will be collected automatically. There are many advantages to have a single source for each piece of information.
On the other hand compiling a table with a couple of columns is very easy and can be conducted in an ad-hoc manner. Single sourcing requires some form of planning as to decide how such a page should look like by defining a blueprint (instead of guessing the relevant columns). For many people it is often more cumbersome to create a new page than to add a new line to an existing table.
So – as often – there is no right or wrong. Choose the tools that are most appropriate to your task!
Resources
- projectdoc Document
- projectdoc is based on projectdoc documents. Creating a projectdoc document is easy: A projectdoc document is a Confluence page using document properties and sections.
- Display Table Macro
- Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided.
- Document Properties Marker Macro
- A table containing document properties. Three columns: name, value and meta data (aka controls) to a property.
- Section Macro
- Renders a section, if the body is not empty. Supports authors to create content, clutter-free rendering without empty sections. Allows to transclude the content.
- Compact Columns
- Tables often require a lot of space to be rendered. This tip shows how to reduce the demand of space.
- Merging Tables and Lists
- References listed in tables and lists may come from different sources. The Table Merger Macro allows to render a number of tables (or lists) as one table (or list).
- Employ the Autolist Feature with Categories
- Categories, tags, and others allow to organize the pages in your wiki. First define categories pages with display table macros. Second tag your pages with these categories. With this two-step process it is easy to have multiple views to link to your information in your wiki.
- Use Display Table for Transclusion References
- It is easy to list all pages that transclude a section from the current page. This allows you, as an author, to check quickly if changes to a document that is transcluded, needs changes to the transcluding documents.
- Think Repositories
- To organize your documentation place documents in a typed repository and add additional views on demand.
- No labels