projectdoc Toolbox

 

 

Doctypes help authors to add their information in a uniform way. This uniform way support the authors to concentrate on the content and not be distracted by formatting or coarse structuring issues. It also helps readers to find the information more quickly.

Teams should only write documentation that is essential and valueable

 

Templates are only a tool. If the information demands it, authors are free to add or adapt the templates to their needs. It is the ease of accessing information that counts, not the adherence to standards.

Please keep in mind to discuss deficiencies with your team members and documentation architects to continuously improve the documentation structure and tools.

Keep your documentation essential, valuable and write it just-in-time!

We assembled some quotes according to documentation writing on the projectdoc homepage. Get inspired on how to design your project documentation!

Doctypes are implemented as page blueprints, which Confluence allows to adjust to your needs. Teams should decide what elements are worthy to use and which should be discarded. After all there must be a return of investment and every asset, which includes documents, is also a (potential) liability.

To get you started with projectdoc quickly we recommend to install the Core Doctypes. With this basic set of blueprints you may start spaces to document topics that are relevant for your team. We also provide (and plan to provide) additional doctype add-ons for other  areas of project documentation.

The projectdoc Add-on provides only a demonstration space and the Blank Document doctype.

Related Documentation

The following links direct you to related documentation within this wiki.

Take an alternative introduction to the Core Doctypes

Or have a look at Doctypes Introduction.

Create a Space

To get started with the Core Doctypes, we recommend to create an Agile Documentation Space.

This provides the basic structure to add new documents easily by the use of home and index pages. This is how the space looks like:

Core Doctypes

The following document types are part of the Core Doctypes Add-on.

 

You may also take an alternative introduction to the Core Doctypes by a Prezi presentation. The presentation provides a good overview by grouping closely related doctypes.

The core doctypes provide the base for your agile documentation work. You may also use them as an inspiration for designing your own templates that meet exactly the requirements of your project.

Please refer to Tour for Document Authors for an introduction on how to use these templates and to Tour for Template Authors for information on how to design your own templates.

 

# Name Short Description Categories
1
Associates two documents.
2
Categorize associations by a type.
3
Categories allow to set document instance of different doctypes in a hierarchy.
4
Describes an information need and use this description as a basis to create and maintain a document.
5
Excerpts are abstracts of information found in a resource, such as a book. If you want to go into more detail for a given resource, there may be multiple excerpts as subpages of the resource document.
6
The model defines the context through which readers acquire skills. The level sets the expectation on the author's techniques to teach.
7
FAQs help to record an answer to a frequently asked question concerning the project, the product, the system or the process.
Documentation
8
Generic Documents provide information where no other doctype matches.
9
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.
10
Metadata documents provide tables of simple key value pairs. This information can be used as space properties to be available for reference on your wiki.
11
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.
12
Categorization of document modules for single sourcing.
13
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.
14
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).
15
Profiles provide views on documents via delegation.
16
Categorize profiles by a type.
17
Quotes relevant for the project. Allows to store the content and metadata to the quote.
18
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.
19
Resources are identified by their media type. This is usually not the MIME type, but human readable string, that identifies the semantic, rather than the syntactic format.
20
Defines a role with its responsibilities, tasks and requirements. Roles are incorporated by stakeholders who take interest in the project. The are also used to define the audience for documents.
21
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.
22
Compile other documents, yet space indices are themselves projectdoc documents. So they can be tagged and grouped.
23
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.
24
Describes a single step of an activity. A step is a generic document that is associated with a document that describes a process. It may be a test log or a howto.
25
Subject documents allow to set document instance of different doctypes in a common context.
26
Document the semantics of a tag. May also be used to document Confluence labels.
27
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.
28
A topic type is a semantic type of the topic. It helps to set the expectations of potential readers.
29
Guided tours through existing information. This allows to aggregate topics for a given question or audience.
30
Document a version of a product or service.
 

Find more doctypes in the extensions!

Extension Doctypes

The following doctypes are not part of the Core Doctypes Add-on, but are (or will soon be) available in separate packages.

Separate add-ons make it easy for teams to select those doctypes that are useful for them and their specific project requirements.

 

Please make sure to check those extension doctypes. Maybe they are not provide exactly to what you require, but they can be a good starting point.

For minor changes Confluence allows to adjust the templates easily. For larger changes we recommend to create a blueprint project and build your own add-on. If you have developers on your team, this may be much easier than you think. Please refer to Tour for Template Authors for an overview on how to do this. We plan to release some of our doctype projects on GitHub to make you get started with your own add-on extensions more quickly.

Name Status Short Description
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.
AVAILABLE
Provides doctypes to document a system or software architecture based on the arc42 Template.
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).
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!
AVAILABLE
A collection of blueprints for Confluence to create and work with documentation for Java projects.
AVAILABLE
A collection of blueprints for Confluence to create and work with documentation for Maven projects.
NOT YET PUBLISHED
Provides doctypes to define the processes and artifacts your team agrees upon. Writing them down make them accessible for anyone - especially for new team members. Keep these documents short and to the point.
NOT YET PUBLISHED
Provides doctypes to document services and systems.
AVAILABLE
Provides doctypes for documenting decisions, risks, open issues and meeting minutes.
AVAILABLE SOON
Provides doctypes for documenting and tracking risks.

Install additional Doctypes!
 

Some doctype 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.

Doctype add-ons with status AVAILABLE are published on the Atlassian Marketplace and Bitbucket.

Doctypes marked as NOT YET PUBLISHED are currently under development. Please get in touch if you need to know about the release plan!

Resources

Document Types and Templates
Document types (or doctypes for short) define a set of properties and sections. Each doctype matches at least one Confluence Page Blueprint. Confluence Page Blueprints are a collection of templates, but often the collection contains only one element.
Doctypes Overview
List of all doctypes provided by add-ons. Provides an overview over doctype IDs and blueprint keys.
Think Repositories
To organize your documentation place documents in a typed repository and add additional views on demand.
Topic is not meant to be multi-purpose
Despite the name of the Topic Doctype, it is not supposed to be used for any topic. Use the Generic Doctype or the Section Doctype for general purposes.