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.

Have a look at the How to document a Software Development Project for details!

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

The query matched no documents.

Core Doctypes

The query matched no documents.

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!