- Created by Robert Reiner, last modified on 25. May 2018
projectdoc Toolbox
Getting started with the projectdoc Toolbox is not easy. Some basic concepts are more than just good-to-know and the number of macros and doctypes may be simply overwhelming. This tip gives some advice on how to get started.
- Audience
- Type
- Level of Experience
- Expected Duration
- 10 min
The projectdoc Toolbox is a collection of macros to make documentation work more easy. This is basically done by reuse of parts of other pages by the use of transclusion and by enhancing navigation by the use of dynamic lists of links.
Getting to learn projectdoc, a look at use and show cases may be helpful as a first step. But different people usually have different approaches to learn. Some may approach by learning concepts first and try them out later. Some prefer to play with the tools and learn concepts and details later. This tip shows some approaches you may choose - not necessarily in the order provided.
Use Cases
Due to the generic nature of the macros, they can be applied in many areas of documentation work. For instance the following use cases are supported:
- Community of Practice
- Build an infrastructure to meet your requirements for a practicing community sharing interest in a given domain.
- Domain Crunching
- Collect and maintain information relevant for your team, project, or organization collaboratively.
- Exploratory Testing
- Run a time-boxed test session based on a test charter to answer questions of stakeholders.
- Glossary
- To work with a domain everybody needs to use the terms unerringly. Create a glossary to create a common understanding of your domains.
- Journals
- 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.
- Library
- Create a library for your project. Reference books, podcasts, videos, and other resources that provide information on the topics relevant for your project.
- Paperwork
- Collaborate to create documents for your stakeholders as a team.
- Product Documentation
- Provide information on how users work with your product. This includes information for users of all roles that interact with the product.
- Project Management
- Make all decisions, issues, and project relevant resources easily accessible for your team. This includes meeting minutes, stakeholder contact information, open issues, and identified risks with their mitigation strategy.
- Reporting
- Tag your documents and create reports on your documents in tabular form
- Service Management Documentation
- Communicate the necessary information on maintaining and using a service of your portfolio.
- Software Architecture Documentation
- Communicate the quality targets, context, and design drivers of your software architecture.
- User Documentation for Java Library
- Provide a standard documentation for users of a library for Java.
- User Documentation for Maven Plugin
- Provide a standard documentation for users of a plugin for Maven.
Use cases provide links to more resources on their topic.
Show Cases
How the macros can be applied to spaces is provided as examples in our show cases:
- Show Case Index Space
- Index space for show cases.
- Show Case Address Book
- Show case with a sample of organizations and persons.
- Show Case Library
- Show case listing resources, including books, articles, and websites.
- Show Case Glossary
- A show case for a glossary using the projectdoc Toolbox.
- Foobar Gadget Generation X
- Show case for a product team space with the projectdoc Toolbox.
- Learning Center
- Show case for tracking team member skills and certification.
- projectdoc New Space Demo
- Shows how a new space created with the Core Doctypes looks like.
- HTML Sanity Checker Architecture Documentation
- Shows an example using the arc42 Template provided by projectdoc Add-on for arc42.
Getting your Hands dirty ...
Learning projectdoc is best done by using it. To do so the projectdoc Toolbox provides a demo space to be created on your Confluence server.
This space explains a couple of projectdoc's concepts and - since the pages are editable in your space, makes it easy to see how it works and maybe play with its macros and pages. The space is also available online at projectdoc Demonstration Space.
There is also a Hands-on Tutorial to guide you through the process of creating some spaces and using tools from the toolbox by a step-by-step tutorial.
Starting with Concepts
As a new user follow this trail to learn the concepts of projectdoc:
- Introduction for new Users
- Basic Concepts and Conventions for projectdoc
- Spaces Introduction
- Doctypes Introduction
- Macros Introduction
A second option is to follow Think big, start small , where you learn the bare minimum and may switcgh to the Hands-on Tutorial quickly.
Approach by Doctype Add-ons
Doctype add-ons provide blueprints for a number of use cases. Installing one (on top of the projectdoc Toolbox and maybe some of our free extensions) may help you get started with topics like documenting software projects, the work of agile teams, or service documentation.
Name | Status | Short Description |
---|---|---|
Core Doctypes | AVAILABLE | Provides a basic set of doctypes to create agile documentation. |
Doctypes for Agile Planning | AVAILABLE | Provides doctypes to collborate with your team. Run iterations and record discoveries that may be of interest at the end of the iteration or for even later reference. Quick notes are more easily added as records to the team's space than to the official documentation tree. Defer the talk to the documentation architect to the end of the iteration (if the discovery is still of interest). |
Doctypes for App Manuals | AVAILABLE SOON | Document macros, page blueprints, space blueprints, and components of your Confluence add-on. |
Doctypes for Business Strategy | AVAILABLE | Mission, vision, strategy for business planning and execution. |
Doctypes for Project Management | AVAILABLE | Provides doctypes for documenting decisions, risks, open issues, and meeting minutes. |
Doctypes for Risk Management | AVAILABLE SOON | Provides doctypes for documenting and tracking risks. |
Doctypes for Service Management | AVAILABLE | Provides doctypes to document services and systems for IT service management (ITSM). |
Doctypes for Software Development | AVAILABLE | Provides doctypes to create documentation in software development projects. The focus is on documenting the architecture of the product, but it includes templates for other software development documentation requirements as well. |
Doctypes for Teamwork | AVAILABLE | Provides doctypes to define the checklists, processes, patterns, tools, and rules your team agrees upon. Writing them down makes them accessible for anyone - especially for new team members. Keep these documents short and to the point! |
Doctypes for V-Modell®XT | AVAILABLE | Use products (templates) from the V-Modell®XT in your Confluence wiki as blueprints! |
projectdoc Add-on for arc42 | AVAILABLE | Provides doctypes to document a system or software architecture based on the arc42 Template. |
projectdoc Developer Diaries | AVAILABLE | Provides doctypes to organize the developer's work by the employment of a diary. Take you personal planning and professional records to the next level! |
projectdoc for Java Developers | AVAILABLE | A collection of blueprints for Confluence to create and work with documentation for Java projects. |
projectdoc for Maven Developers | AVAILABLE | A collection of blueprints for Confluence to create and work with documentation for Maven projects. |
Some doctype and extension add-ons are currently still under development. They will be available for download on the Atlassian Marketplace soon.
Add-ons labelled as AVAILABLE SOON are already published on Bitbucket.
ABOUT TO BE AVAILABLE indicates that the add-on has been released to the Atlassian Marketplace and is waiting for approval.
Add-ons with status AVAILABLE are published on the Atlassian Marketplace and on Bitbucket.
Add-ons marked as NOT YET PUBLISHED are currently under development. Please get in touch if you need to know about the release plan!
POSTPONED indicates that the add-on is no longer under active development to be released on the Atlassian Marketplace, but still available on Bitbucket.
Learning by Tips
Tips show various aspects of the projectdoc Toolbox. It includes arbitrary, but important ways on how to use its tools.
The list contains a number of tips that originate from questions asked by customers.
One-on-Ones
If you would like to discuss your requirements with one of our team members, please schedule a 1:1!
In this session, typically an online chat or call about one hour long, we will discuss your topics and show how the projectdoc Toolbox can be used to organize your spaces.