- Created by Robert Reiner, last modified on 21. Jun 2023
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.
Have a look at the How to document a Software Development Project for details!
Learn projectdoc
- The projectdoc Introduction for an introduction to basic concepts of projectdoc
- Follow the Hands-on Tutorial to start working wit ht projectdoc Toolbox
- Check out the Project Documentation Basics to learn the fundamental concepts of projectdoc
- 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.
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.
Get aware of your Constraints
With your stakeholders at hand, query for constraints the project has to adhere to.
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
# | Name | Short Description | Set | Documentation Type | Categories |
---|---|---|---|---|---|
1 | arc42 Template | The blueprint of the arc42 Template creates a tree of pages in the Confluence space. | arc42 | Q4 - System | / Volume |
2 | Architecture 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 Development | Q2 - Project | / Process / Design |
3 | Architecture Alternative Type | Group architecture alternatives by their type. | Software Development | Q1 - Process | / Organisation / Specific |
4 | Architecture Aspect | Document an aspect of your architecture. Something orthogonal or cross-functional like logging, exception handling or configurability. | Software Development | Q4 - System | / Process / Design |
5 | Architecture Aspect Type | Group architecture aspects by their type. | Software Development | Q1 - Process | / Organisation / Specific |
6 | Architecture 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 Development | Q2 - Project | / Process / Design |
7 | Architecture Decision Type | Architecture decisions are group by their types. A commonly used decision type is 'Architecture'. | Software Development | Q1 - Process | / Organisation / Specific |
8 | Artifact | 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 Development | Q1 - Process | |
9 | Artifact Type | Artifact types categorize artifacts. | Software Development | Q2 - Project | |
10 | Blackbox | Describe as a Blackbox the elements of a view where only the externally visible properties are relevant. | Software Development | Q4 - System | / Process / Design |
11 | Blackbox Type | Group blackboxes by their type. | Software Development | Q1 - Process | / Organisation / Specific |
12 | Code | Describe the codes that are part of the product's API. | Software Development | Q3 - Product | / Process / Implementation |
13 | Code Type | Code types categorize codes, used in logging or exception handling. | Software Development | Q2 - Project | |
14 | Component | 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 Development | Q4 - System | / Process / Design |
15 | Component Type | Component types categorize components. | Software Development | Q2 - Project | |
16 | Data Type Type | Data type types categorize data types. | Software Development | Q2 - Project | |
17 | Environment | Document logical or physical groups of nodes. | Software Development | Q2 - Project | |
18 | Environment Type | Type of an environment used by the project to deploy the application or the solution. | Software Development | Q1 - Process | |
19 | Feature | Documents a feature of the product. The top features define the main aspects of the product. | Software Development | Q3 - Product | / Process / Analysis |
20 | Feature Type | Feature types categorize features. | Software Development | Q2 - Project | |
21 | Interface | Interfaces document how elements of the system communicate with elements of this and other systems. | Software Development | Q4 - System | / Process / Design |
22 | Interface Type | Group interfaces by their type. | Software Development | Q1 - Process | / Organisation / Specific |
23 | Node | Nodes are part of environments where artifacts are deployed to. | Software Development | Q2 - Project | |
24 | Node Type | Node types categorize nodes. | Software Development | Q2 - Project | |
25 | Out 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 Development | Q2 - Project | / Process / Analysis |
26 | Out Item Type | Out item types categorize out items. | Software Development | Q2 - Project | |
27 | Project Constraint | Project Constraints limit the options of a project. | Software Development | Q2 - Project | / Process / Analysis |
28 | Project Constraint Type | Project constraint types categorize project constraints. | Software Development | Q2 - Project | |
29 | Project Vision | Frame the vision for a project or iteration. | Software Development | Q2 - Project | / Process / Analysis |
30 | Project Vision Type | Types to categorize vision statements for projects. | Software Development | Q4 - System | |
31 | Property | Properties are part of the configuration options of a system. | Software Development | Q3 - Product | / Process / Implementation |
32 | Property Type | Property types categorize properties of products, such as parameters or configuration options. | Software Development | Q2 - Project | |
33 | Quality | Qualities describe desired aspects of the product. | Software Development | Q1 - Process | / Organisation / Specific |
34 | Quality Scenario | Quality Scenarios document required qualities. | Software Development | Q4 - System | / Process / Test |
35 | Quality Scenario Type | Quality scenario types categorize quality scenarios. | Software Development | Q4 - System | |
36 | Quality Target | Documents a quality target for a product. | Software Development | Q2 - Project | / Process / Analysis |
37 | Quality Target Type | Group quality targets by their type. | Software Development | Q1 - Process | / Organisation / Specific |
38 | Requirement | Documents requirements of a product. | Software Development | Q2 - Project | / Process / Analysis |
39 | Requirement Type | Categorization of requirements for a product. | Software Development | Q1 - Process | / Organisation / Specific |
40 | Technical Debt | Technical Debts track issues to be paid back. | Software Development | Q2 - Project | / Process / Implementation |
41 | Technical Debt Type | Technical Debts are grouped by the area they address. | Software Development | Q1 - Process | / Organisation / Specific |
42 | Test Case | Document a test case of your project. | Software Development | Q4 - System | / Process / Test |
43 | Test Case Type | Test case types categorize test cases. | Software Development | Q4 - System | |
44 | Test Charter | Defines a charter to run an exploratory test session. | Software Development | Q4 - System | / Process / Test |
45 | Test Charter Type | Test charter types categorize test charters. | Software Development | Q4 - System | |
46 | Test Data | Document data used for test cases. | Software Development | Q4 - System | / Process / Test |
47 | Test Data Type | Test data types categorize test data. | Software Development | Q4 - System | |
48 | Test Report | Documents the results of a test session for the sponsoring stakeholders. | Software Development | Q4 - System | / Process / Test |
49 | Test Report Type | Test report types categorize test reports. | Software Development | Q4 - System | |
50 | Test Session | Defines a document to collect information during a test session. | Software Development | Q4 - System | / Process / Test |
51 | Test Session Type | Test session types categorize test sessions. | Software Development | Q4 - System | |
52 | Use Case | Defines a use case of the product. | Software Development | Q4 - System | / Process / Design |
53 | Use Case Type | Use case types categorize use cases. | Software Development | Q4 - System | |
54 | User Character | User Characters are the actors of user stories. They include personas and extreme characters. | Software Development | Q2 - Project | / Process / Analysis |
55 | User Character Type | User character types categorize user characters. | Software Development | Q4 - System | |
56 | View | 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 | |
57 | View Type | Groups the views at a system. | Software Development | Q1 - Process | / Organisation / Specific |
58 | Whitebox | Describe as a Whitebox the elements of a view where only the relations of internal elements are relevant. | Software Development | Q4 - System | / Process / Design |
59 | Whitebox Type | Group whiteboxes by their type. | Software Development | Q1 - Process | / Organisation / Specific |
Core Doctypes
Name | Short 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 | 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. |
Metadata Type | Categorize metadata documents by a type. |
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!