- Created by Robert Reiner, last modified on 04. Jan 2018
Build an infrastructure to meet your requirements for a practicing community sharing interest in a given domain.
- Categories
A community of practice (Wikipedia) needs a communication platform to collaborate on a subject of their interest. To share experience on practicing and working on knowledge.
Confluence is a team collaboration platform. The projectdoc Toolbox support teams to write documentation in a modular style. Having separate documents for topics makes it even easier to work on a subject collaboratively. Team members edit different documents concurrently and assemble them by using transclusion or reference.
This makes this Wiki platform a perfect fit as a tool set for a community of practice in many cases.
The projectdoc Toolbox provides tools to create journals on a personal (Diary from the projectdoc Developer Diaries add-on) and on a team level (using the Iteration doctype of the Doctypes for Agile Planning add-on). The Agile Planning add-on also provides backlogs (Improvement doctype) for a document-based tracking of areas of improvement.
The Core Doctypes allow you to define a library to keep track of external resources, have information about people of the community and relevant external experts in form of a address book, and the Glossary Item doctype to create and maintain a glossary of terms of your domain.
Furthermore the Doctypes for Teamwork provide doctypes to define the rules of your communities communication, specify proven practices in the form of patterns and document a shared repertoire of tools. Using workspaces to spike on new areas and topic spaces to document and maintain relevant information on the subject.
That is not to say that communities need all of the tools sketched out above. This is simply a set of tools to select from and adapt to the community's requirements to work effectively and efficiently together.
Creating an Infrastucture
Some notes on how to create an infrastucture for a community of practice.
If you are new to Confluence and the projectdoc Toolbox, the first space you may want to create is the Index Space. This space is typically the root of a other spaces and provides some commonly used configuration (like categories and tags).
You may want to create a separate Address Book space, Library Space, and Glossary space. If not, store these resource in the index space.
All these spaces are commonly used by teams and are created only once. So you usually have one address book, one library, etc. per site.
If you need to keep things separate you can have all this information as part of your index space.
To define the subject you are investigating we recommend to use the Tag doctype. Use the tag homepage of your index space as the parent to this document.
There is a Subject doctype. But subjects are typically exclusive for a document, while tags are not. Categories are often unwieldy since they require to have entered the whole path.
Use the Organization doctype to add information about the community. The organization document is typically stored on its doctype homepage in the the Address Book space.
You may add Person documents to describe basic information (typically contact information) and add a Stakeholder document to add information that is relevant for a given person in the context of the community. The person document is typically stored on its doctype homepage in the the Address Book space, while the stakeholder document is part of the community space (may be an teamwork space and the organization document should probably point to the space - and vice versa).
The teamwork space will include the current rules and descriptions of currently used tools.
Create an Agile Planning space and have a team journal in the form of Iteration documents. The members of the community may run their own personal journal where they track events. You may use each or one of them, whatever suites your needs of communication more. Note that these spaces will contain records (which document events that need not to be updated. The Teamwork space created in the last step contains documents which require to be up-to date (for instance if a rule is changed, removed, or added, the space needs to be updated accordingly).
For spikes that require more room you may use additional workspaces for a subset of the community.
Do not get lost in empty spaces!
Create workspaces at the moment they are needed. Otherwise there is the tendency to have a large number of spaces with little content. Keep this content in the Agile Planning space as long as you are comfortable with that.
Put each information to its topic space. Topic spaces contain documents that need to reflect the current state of knowledge. A community may maintain only one topic space for their subject of interest.
The teamwork space contains the rules and tools of the community.
The workspaces (including journals) log events with interesting and useful information discovered by the team members.
The topic space contains the current status of knowledge of the community on the subject.
In addition there may be specialized attachment spaces kept separate from these other spaces.
- address book
- library
- glossary
Resources
Information Material
The following list of resources provides background information and reference other use cases relevant for community work based on the projectdoc Toolbox for Confluence.
| Resource | Short Description | Type |
|---|---|---|
Index spaces provide basic configuration via space properties and homepages for commonly used document types. | topic | |
Collect and maintain information relevant for your team, project, or organization collaboratively. | business-use-case | |
To work with a domain everybody needs to use the terms unerringly. Create a glossary to create a common understanding of your domains. | business-use-case | |
You want to track your findings? Either with your team or individual? The projectdoc Toolbox supports teams to create project or team journals and individual team members to keep a professional diary. | business-use-case | |
Collaborate to create documents for your stakeholders as a team. | business-use-case | |
Organize information about persons and organizations. | topic | |
Get started with the projectdoc Toolbox: learning by doing | topic | |
Concepts central to projectdoc. Things users have to understand to get the most out of using projectdoc. | topic | |
Tour through the documentation for users who want to learn to create documents based on projectdoc doctypes. | tour | |
Home and index pages help to organize documents by type. For each doctype there is a homepage and and index page. The homepage shows the central documents that are added to it (immediate children). Index pages list all documents of the space, regardless of their location. | topic | |
A set of Confluence spaces showing projectdoc in action. | topic |
Doctypes
The following doctypes (blueprints based on the projectdoc Toolbox) provided page blueprints to provide the infrastructure for a community of practice.
| Resource | Short Description | Categories |
|---|---|---|
A description of a given topic. A topic may describing or explaining a concept, a task to accomplish or a reference. There are a couple of topic types that set the expectations for the reader. Instances of the topic doctype usually have independent lifetimes from any referencing documents. | ||
Sections of a document are typically part of a document. But the size of sections may vary. To support a team to write collaboratively on the documentation, a larger document may be subdivided into external section documents. | ||
A documentation module is a fragment which is usually transcluded by other documents. The lifetime of a module document is independent of the lifetimes of the documents that reference it. | ||
Guided tours through existing information. This allows to aggregate topics for a given question or audience, thus providing a view on a topic. | ||
Information about organizations that take a part in the project. You may collect common information here for all persons that belong to an organization, such as address or homepage. | ||
Provides information about a person. This includes contact information (important if the person is relevant for the team) or information about the competences (if the person is an author about a topic relevant for the project). | ||
A party that takes interest in a project. The stakeholder is either a real person, an organization or group, or represents a class of individuals, groups or organizations. | ||
Resources are books, webpages, videocasts relevant for the project. Add important information to your project about resources that lie outside the control of your team. | ||
Glossary items are part of the domain glossary for the project. Glossaries support the team to use terms of the domain consistently in conversations and documentation. | ||
The homepage of a developer's daily diary pages. Consider to add your diary to your personal space! | ||
Document an Iteration that may be linked from JIRA. Allows the team to set the goal and add notes relevant to a particular iteration. | ||
Document the semantics of a tag. May also be used to document Confluence labels. |
Each doctype can be categorized by a doctype-specific type property (e.g. Topic Type for the Topic doctype).
Macros
The following macros of the projectdoc Toolbox support communities of practice.
| Resource | Short Description | Categories |
|---|---|---|
Sections of a document are typically part of a document. But the size of sections may vary. To support a team to write collaboratively on the documentation, a larger document may be subdivided into external section documents. | ||
Marks a piece of content within a document. This content can be referenced for transclusion. | ||
Transcludes content from a document marked with the content marker macro. | ||
Renders transcluded content fetched from documents of a result set. | ||
Lists references to projectdoc documents in a table. Allows to select document properties for columns. Also non-list representations are provided. | ||
Renders a predefined list of documents in a table. | ||
Renders a box containing a pending message to be handled later by the author. | ||
Renders a box containing a feedback message from a reader with write privilege. | ||
Renders a box containing a fault message reported by a team member for the author. | ||
Renders transcluded content fetched from documents of a result set. | ||
Merges tables (and lists) into one table (or list). |
