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.
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.
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.
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 | The blueprint of the arc42 Template creates a tree of pages in the Confluence space. |
||||
| 2 | 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. |
||||
| 3 | Group architecture alternatives by their type. |
||||
| 4 | Document an aspect of your architecture. Something orthogonal or cross-functional like logging, exception handling or configurability. |
||||
| 5 | Group architecture aspects by their type. |
||||
| 6 | 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. |
||||
| 7 | Architecture decisions are group by their types. A commonly used decision type is 'Architecture'. |
||||
| 8 | 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. |
||||
| 9 | Artifact types categorize artifacts. |
||||
| 10 | Describe as a Blackbox the elements of a view where only the externally visible properties are relevant. |
||||
| 11 | Group blackboxes by their type. |
||||
| 12 | Describe the codes that are part of the product's API. |
||||
| 13 | Code types categorize codes, used in logging or exception handling. |
||||
| 14 | 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. |
||||
| 15 | Component types categorize components. |
||||
| 16 | Data type types categorize data types. |
||||
| 17 | Document logical or physical groups of nodes. |
||||
| 18 | Type of an environment used by the project to deploy the application or the solution. |
||||
| 19 | Documents a feature of the product. The top features define the main aspects of the product. |
||||
| 20 | Feature types categorize features. |
||||
| 21 | Interfaces document how elements of the system communicate with elements of this and other systems. |
||||
| 22 | Group interfaces by their type. |
||||
| 23 | Nodes are part of environments where artifacts are deployed to. |
||||
| 24 | Node types categorize nodes. |
|
|||
| 25 | 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. |
||||
| 26 | Out item types categorize out items. |
||||
| 27 | Project Constraints limit the options of a project. |
||||
| 28 | Project constraint types categorize project constraints. |
||||
| 29 | Frame the vision for a project or iteration. |
||||
| 30 | Types to categorize vision statements for projects. |
||||
| 31 | Properties are part of the configuration options of a system. |
||||
| 32 | Property types categorize properties of products, such as parameters or configuration options. |
||||
| 33 | Qualities describe desired aspects of the product. |
||||
| 34 | Quality Scenarios document required qualities. |
||||
| 35 | Quality scenario types categorize quality scenarios. |
||||
| 36 | Documents a quality target for a product. |
||||
| 37 | Group quality targets by their type. |
||||
| 38 | Documents requirements of a product. |
||||
| 39 | Categorization of requirements for a product. |
||||
| 40 | Technical Debts track issues to be paid back. |
||||
| 41 | Technical Debts are grouped by the area they address. |
||||
| 42 | Document a test case of your project. |
||||
| 43 | Test case types categorize test cases. |
||||
| 44 | Defines a charter to run an exploratory test session. |
||||
| 45 | Test charter types categorize test charters. |
||||
| 46 | Document data used for test cases. |
||||
| 47 | Test data types categorize test data. |
||||
| 48 | Documents the results of a test session for the sponsoring stakeholders. |
||||
| 49 | Test report types categorize test reports. |
||||
| 50 | Defines a document to collect information during a test session. |
||||
| 51 | Test session types categorize test sessions. |
||||
| 52 | Defines a use case of the product. |
||||
| 53 | Use case types categorize use cases. |
||||
| 54 | User Characters are the actors of user stories. They include personas and extreme characters. |
||||
| 55 | User character types categorize user characters. |
||||
| 56 | Different views on the product help to document the system and its architecture. Typical views are building block, runtime, or deployment. |
||||
| 57 | Groups the views at a system. |
||||
| 58 | Describe as a Whitebox the elements of a view where only the relations of internal elements are relevant. |
||||
| 59 | Group whiteboxes by their type. |
Core Doctypes
| Name | Short Description |
|---|---|
Associates two documents. |
|
Categorize associations by a type. |
|
Categories allow to set document instance of different doctypes in a hierarchy. |
|
Categorize categories by a type. |
|
Describes an information need and use this description as a basis to create and maintain a document. |
|
Categorize charters by a type. |
|
Add cycles to group cycle phases. |
|
Cycle phases define phases that are bound to a cycle, such as lifecycles or iterations. |
|
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. |
|
Categorize excerpts by a type. |
|
Defines the context through which readers acquire skills. The level sets the expectation on the author's techniques to teach. |
|
Categorize experience levels by a type. |
|
FAQs help to record an answer to a frequently asked question concerning the project, the product, the system or the process. |
|
Categorize FAQs by a type. |
|
Generic Documents provide information where no other doctype matches. |
|
Categorize generic documents by a type. |
|
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. |
|
Categorize glossary items by a 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. |
|
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. |
|
Categorize metadata documents by a type. |
|
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. |
|
Categorization of document modules for single sourcing. |
|
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. |
|
Categorize organizations by a type. |
|
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). |
|
Categorize persons by a type. |
|
Profiles provide views on documents via delegation. |
|
Categorize profiles by a type. |
|
Quotes relevant for the project. Allows to store the content and metadata to the quote. |
|
Categorize quotes by a type. |
|
Organizes glossary items. |
|
Categorize relations by a type. |
|
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. |
|
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. |
|
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. |
|
Categorize roles by a type. |
|
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. |
|
Categorize sections by a type. |
|
Compile other documents, yet space indices are themselves projectdoc documents. So they can be tagged and grouped. |
|
Categorize space indexes by a type. |
|
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. |
|
Categorize stakeholders by a type. |
|
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. |
|
Categorize steps by a type. |
|
Subject documents allow to set document instance of different doctypes in a common context. |
|
Categorize subjects by a type. |
|
Document the semantics of a tag. May also be used to document Confluence labels. |
|
Categorize tags by a type. |
|
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. |
|
A topic type is a semantic type of the topic. It helps to set the expectations of potential readers. |
|
Guided tours through existing information. This allows to aggregate topics for a given question or audience, thus providing a view on a topic. |
|
Document a version of a product or service. |
|
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!