projectdoc Toolbox

How to start your software project documentation? Here are the steps to get started with Confluence and the projectdoc Toolbox.

There are many books and information on the internet on how you can document your software or system documentation. Therefore we do not want to give an in-depth discussion on this topic, but provide you a pragmatic quick start on how to start you documentation on your wiki.

Prerequisites

Here are some steps to consider to take first.

Install Software

The projectdoc Toolbox for Confluence with a collection of free doctype add-ons need to be installed.

Learn projectdoc

  1. The projectdoc Introduction for an introduction to basic concepts of projectdoc
  2. Follow the Hands-on Tutorial to start working wit ht projectdoc Toolbox
  3. Check out the Project Documentation Basics to learn the fundamental concepts of projectdoc
  4. Visit the arc42 website to learn more about organizing your software or system architecture documentation

Create a Space

Follow the instructions shown in Create your Software Documentation Space to create a space or add the arc42 Template to an existing space.

Contents

The arc42 Template

To document your software or system architecture, follow the arc42 Template. The documentation for the template is available online.

If you are using projectdoc, it is recommended to create a modular documentation. That is, you create a separate document for each topic you want to cover. If you identify a role or a stakeholder, use the Role or Stakeholder template and store the document on the doctype's homepage.

Example

 

Have a look at the HTML Sanity Checker space for an example documentation based on the arc42 Template.

Here is an example with the Stakeholder Template Wizard:

Since the checkbox "Send to Homepage" is checked, the document will be stored on the stakeholder homepage regardless of the page in the browser.

Documents do not show up on Space Homepage?

 

On the chapter pages of the arc42 Template the queries are restricted.

For instance the list of stakeholders on 'Introduction and Goals' is restricted to those documents of type Stakeholder that are marked with the Tag named 'primary'.

So in case you are looking for list to get filled automatically, but they do not: Check the selection criteria of the query macros!

The arc42 SWAD will then automatically reference the documents you create by the use of the Display Table Macro. You may want to adjust the select criteria for the queries to meet you needs, but the defaults will get you started. Not all information is provided by documents that are stored on the doctype homepages. Some information is added directly to the generated pages of the arc42 SWAD (such as the Solution Strategy).

 

If you want to keep it modular, use the Module Template and transclude the content. This approach is recommended if you

  • use the content from several pages.
  • collaborate simultaneously with your team on the creation of your documentation.

To help you get started with the arc42 Template and projectdoc, we introduce to you some of the templates of the doctype add-ons. So here we go!

Find your Stakeholders

The project is under high risk to fail, if you fail to identify the important stakeholders of your project.

Use the Stakeholder template to document your stakeholders.

 

You may choose to document stakeholders as Roles, Persons or Organizations. The Stakeholder documents reference the basic data and allows to store information about the interests of the stakeholder for your project.

Quality Targets

It is important to define and prioritize the quality targets for your project. This will keep your team on track to come to decisions on architectural issues.

 
You may prefer to define the qualities by the Quality template and reuse this information for several of your projects.

Get aware of your Constraints

With your stakeholders at hand, query for constraints the project has to adhere to.

 
You may prefer to use a requirement management tool for this task. In this case reference the requirements in your tool.

Define your Solution Strategy

Define your solution strategy. Use chapter 4 of your SWAD.

Document your System Context

Use the View Template to document the context of your system.

Building Blocks

The most important view after the system context is usually the view on the building blocks of your system. Create a view document and then drill deeper into your system by alternating between the Blackbox View of your components and its Whitebox View.

 

Alternatively you may use the Component Template to create a component document and add view documents to them.

Document your Decisions

Document your important decisions on the architecture level.

That's all?

Probably not. There may be much more information you want to cover for your team members or other stakeholders. Here is a list of templates you may choose from.

Software Development Doctypes

#NameShort DescriptionSetDocumentation TypeCategories
1arc42 Template
The blueprint of the arc42 Template creates a tree of pages in the Confluence space.
arc42Q4 - System / Volume
2Architecture Alternative
Document a possible option for an architecture decision. Choose this document type to describe the alternative for a decision in more detail. This is typically a subpage of an architecture decision document.
Software DevelopmentQ2 - Project / Process / Design
3Architecture Alternative Type
Group architecture alternatives by their type.
Software DevelopmentQ1 - Process / Organisation / Specific
4Architecture Aspect
Document an aspect of your architecture. Something orthogonal or cross-functional like logging, exception handling or configurability.
Software DevelopmentQ4 - System / Process / Design
5Architecture Aspect Type
Group architecture aspects by their type.
Software DevelopmentQ1 - Process / Organisation / Specific
6Architecture Decision
Document a architecture decision for an option. This is useful to state the reasons and the options that have been evaluated. Later other team members will have it easier to understand the decision.
Software DevelopmentQ2 - Project / Process / Design
7Architecture Decision Type
Architecture decisions are group by their types. A commonly used decision type is 'Architecture'.
Software DevelopmentQ1 - Process / Organisation / Specific
8Artifact
Document requirements you impose on artifacts. Artifacts are created by processes defined and used by the team. This includes assemblies created by the build process, source code artifacts or reports.
Software DevelopmentQ1 - Process
9Artifact Type
Artifact types categorize artifacts.
Software DevelopmentQ2 - Project
10Blackbox
Describe as a Blackbox the elements of a view where only the externally visible properties are relevant.
Software DevelopmentQ4 - System / Process / Design
11Blackbox Type
Group blackboxes by their type.
Software DevelopmentQ1 - Process / Organisation / Specific
12Code
Describe the codes that are part of the product's API.
Software DevelopmentQ3 - Product / Process / Implementation
13Code Type
Code types categorize codes, used in logging or exception handling.
Software DevelopmentQ2 - Project
14Component
Components are part of a view on a system. A component may refer to a enclosed element or to a complete system of its own.
Software DevelopmentQ4 - System / Process / Design
15Component Type
Component types categorize components.
Software DevelopmentQ2 - Project
16Data Type Type
Data type types categorize data types.
Software DevelopmentQ2 - Project
17Environment
Document logical or physical groups of nodes.
Software DevelopmentQ2 - Project
18Environment Type
Type of an environment used by the project to deploy the application or the solution.
Software DevelopmentQ1 - Process
19Feature
Documents a feature of the product. The top features define the main aspects of the product.
Software DevelopmentQ3 - Product / Process / Analysis
20Feature Type
Feature types categorize features.
Software DevelopmentQ2 - Project
21Interface
Interfaces document how elements of the system communicate with elements of this and other systems.
Software DevelopmentQ4 - System / Process / Design
22Interface Type
Group interfaces by their type.
Software DevelopmentQ1 - Process / Organisation / Specific
23Node
Nodes are part of environments where artifacts are deployed to.
Software DevelopmentQ2 - Project
24Node Type
Node types categorize nodes.
Software DevelopmentQ2 - Project
25Out Item
Out Items record topics that are out of the scope of the project. This is useful for project inception and for reference in the future.
Software DevelopmentQ2 - Project / Process / Analysis
26Out Item Type
Out item types categorize out items.
Software DevelopmentQ2 - Project
27Project Constraint
Project Constraints limit the options of a project.
Software DevelopmentQ2 - Project / Process / Analysis
28Project Constraint Type
Project constraint types categorize project constraints.
Software DevelopmentQ2 - Project
29Project Vision
Frame the vision for a project or iteration.
Software DevelopmentQ2 - Project / Process / Analysis
30Project Vision Type
Types to categorize vision statements for projects.
Software DevelopmentQ4 - System
31Property
Properties are part of the configuration options of a system.
Software DevelopmentQ3 - Product / Process / Implementation
32Property Type
Property types categorize properties of products, such as parameters or configuration options.
Software DevelopmentQ2 - Project
33Quality
Qualities describe desired aspects of the product.
Software DevelopmentQ1 - Process / Organisation / Specific
34Quality Scenario
Quality Scenarios document required qualities.
Software DevelopmentQ4 - System / Process / Test
35Quality Scenario Type
Quality scenario types categorize quality scenarios.
Software DevelopmentQ4 - System
36Quality Target
Documents a quality target for a product.
Software DevelopmentQ2 - Project / Process / Analysis
37Quality Target Type
Group quality targets by their type.
Software DevelopmentQ1 - Process / Organisation / Specific
38Requirement
Documents requirements of a product.
Software DevelopmentQ2 - Project / Process / Analysis
39Requirement Type
Categorization of requirements for a product.
Software DevelopmentQ1 - Process / Organisation / Specific
40Technical Debt
Technical Debts track issues to be paid back.
Software DevelopmentQ2 - Project / Process / Implementation
41Technical Debt Type
Technical Debts are grouped by the area they address.
Software DevelopmentQ1 - Process / Organisation / Specific
42Test Case
Document a test case of your project.
Software DevelopmentQ4 - System / Process / Test
43Test Case Type
Test case types categorize test cases.
Software DevelopmentQ4 - System
44Test Charter
Defines a charter to run an exploratory test session.
Software DevelopmentQ4 - System / Process / Test
45Test Charter Type
Test charter types categorize test charters.
Software DevelopmentQ4 - System
46Test Data
Document data used for test cases.
Software DevelopmentQ4 - System / Process / Test
47Test Data Type
Test data types categorize test data.
Software DevelopmentQ4 - System
48Test Report
Documents the results of a test session for the sponsoring stakeholders.
Software DevelopmentQ4 - System / Process / Test
49Test Report Type
Test report types categorize test reports.
Software DevelopmentQ4 - System
50Test Session
Defines a document to collect information during a test session.
Software DevelopmentQ4 - System / Process / Test
51Test Session Type
Test session types categorize test sessions.
Software DevelopmentQ4 - System
52Use Case
Defines a use case of the product.
Software DevelopmentQ4 - System / Process / Design
53Use Case Type
Use case types categorize use cases.
Software DevelopmentQ4 - System
54User Character
User Characters are the actors of user stories. They include personas and extreme characters.
Software DevelopmentQ2 - Project / Process / Analysis
55User Character Type
User character types categorize user characters.
Software DevelopmentQ4 - System
56View
Different views on the product help to document the system and its architecture. Typical views are building block, runtime, or deployment.
Software Development / Process / Design
57View Type
Groups the views at a system.
Software DevelopmentQ1 - Process / Organisation / Specific
58Whitebox
Describe as a Whitebox the elements of a view where only the relations of internal elements are relevant.
Software DevelopmentQ4 - System / Process / Design
59Whitebox Type
Group whiteboxes by their type.
Software DevelopmentQ1 - Process / Organisation / Specific

Core Doctypes

NameShort Description
Association
Associates two documents.
Association Type
Categorize associations by a type.
Category
Categories allow to set document instance of different doctypes in a hierarchy.
Category Type
Categorize categories by a type.
Charter
Describes an information need and use this description as a basis to create and maintain a document.
Charter Type
Categorize charters by a type.
Cycle

Add cycles to group cycle phases.

Cycle Phase

Cycle phases define phases that are bound to a cycle, such as lifecycles or iterations.

Excerpt
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.
Excerpt Type
Categorize excerpts by a type.
Experience Level
Defines the context through which readers acquire skills. The level sets the expectation on the author's techniques to teach.
Experience Level Type
Categorize experience levels by a type.
FAQ
FAQs help to record an answer to a frequently asked question concerning the project, the product, the system or the process.
FAQ Type
Categorize FAQs by a type.
Generic
Generic Documents provide information where no other doctype matches.
Generic Type
Categorize generic documents by a type.
Glossary Item
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.
Glossary Item Type
Categorize glossary items by a type.
Media Type
Resources are identified by their media type. This may be the MIME type, but also a human readable string, that identifies the syntactic format.
Media Type Type
Categorize media types by their type.

Metadata documents provide tables of simple key/value pairs. This information can be used as an aspect or as additional space properties to be available for reference on your wiki.

Module
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.
Module Type
Categorization of document modules for single sourcing.
Organization
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.
Organization Type
Categorize organizations by a type.
Person
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).
Person Type
Categorize persons by a type.
Profile
Profiles provide views on documents via delegation.
Profile Type
Categorize profiles by a type.
Quote
Quotes relevant for the project. Allows to store the content and metadata to the quote.
Quote Type
Categorize quotes by a type.
Relation
Organizes glossary items.
Relation Type
Categorize relations by a type.
Resource
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.
Resource Type
Resources are identified by their type. This is not the MIME type, but human readable string, that identifies the semantic, rather than the syntactic format.
Role
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.
Role Type
Categorize roles by a type.
Section
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.
Section Type
Categorize sections by a type.
Space Index
Compile other documents, yet space indices are themselves projectdoc documents. So they can be tagged and grouped.
Space Index Type
Categorize space indexes by a type.
Stakeholder
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.
Stakeholder Type
Categorize stakeholders by a type.
Step
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.
Step Type
Categorize steps by a type.
Subject
Subject documents allow to set document instance of different doctypes in a common context.
Subject Type
Categorize subjects by a type.
Tag
Document the semantics of a tag. May also be used to document Confluence labels.
Tag Type
Categorize tags by a type.
Topic
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.
Topic Type
A topic type is a semantic type of the topic. It helps to set the expectations of potential readers.
Tour
Guided tours through existing information. This allows to aggregate topics for a given question or audience, thus providing a view on a topic.
Version
Document a version of a product or service.
Version Type
Categorize versions by a type.

If the templates do not match your requirements, adjust them! If you feel overwhelmed by the amount of templates, stick to Topics or Generic documents. But using a doctype for a particular information usually makes it easier to select it from your queries.

 

Keep in mind that agile documentation is not about filling out templates. Templates exist to guide you documenting an aspect of your project you deem worth noting. Every document is a liability since it has to be maintained. Therefore keep an eye on the creation and maintenance cost of each document!