The development of software products needs cross-functional teams. The team is not limited to the people who actually write and test the code. There are technical writers to create the documentation, marketing specialists, product owners, domain experts and many more. And the list of stakeholders – people taking interest in the project or product – makes this crowd even larger: managers to provide sufficient resources, customers, users and also many more.

While we believe that every member of a team needs to have the freedom to select the tools that are most efficient and effective to use for their tasks, we also believe that there has to be an information system that is capable to provide access to all information for each and every stakeholder. A wiki (or team collaboration platform) – like Atlassian Confluence – is a great tool for this task.

In this howto we explain how to get started to document a software project using the PDAC1 and Atlassian Confluence. We assume that many aspects are relevant for teams independent of their chosen infrastructure / toolset – that is if your tooling is different, this aspects still apply. The projectdoc Toolbox provides tools, mainly macros and blueprints for different document types (called doctypes in projectdoc lingo), which makes it easier for teams in their task to collaborate and share information with all stakeholders.

After giving a brief introduction of some of the different aspects of documentation, we focus on how to start documenting your software architecture with this set of tools.

To document a software project does not only require the systems or architecture documentation. In Software Architecture Documentation we list the four quadrants:

1. Process Documentation
2. Project Documentation
3. System Documentation
4. User Documentation

Here are some more examples on how to use the PDAC1 to provide project relevant information.

Developers may keep journals to track open questions and interesting findings. These journals may be open for all team members to find relevant information on project topics.

Besides the individual journals the team may write a team journal to plan and run iterations or sprints. The Doctypes for Agile Planning provide templates for these communication needs.

Use Doctypes for Teamwork to define checklists, processes, patterns, tools, and rules a team agrees upon. Writing them down makes them accessible for anyone - especially for new team members. Keep these documents short and to the point!

Doctypes for Project Management provides tools to communicate important project information with decisions, risks, open issues, and meeting minutes.

A glossary is helpful for most project and product documentations.

A project library collects relevant information for the project that is typically provided by external resources. These resources include books, website, blogs, or articles. The library is especially helpful to provide information about the domain or technology stack for new team members.

In order to create a glossary the team may need to do some domain crunching. Create a separate space to collect all information relevant for the domain.

Add things you learned about the domain that should be accessible beyond the scope of the current iteration or sprint of your team.

Different stakeholders have different information and communication needs.

Some stakeholder need information for a given topic. In this case the team may create a workspace to collaborate to create the requested document. After the information is delivered the space may be archived.

Teams whose builds depend on Maven and that use automation heavily typically end up in writing their own plugins for Maven. Although these plugins are often only released for internal use, developers who employ these plugins need to have access to proper documentation.

Teams using continuous deployment may choose to create libraries to modularize their code base. Each library is a product of its own with its own release cycle. Especially if the library is made public available, a sound and similar structure of the documentation helps developers to find information on how to use this library easily.