What software development teams should document in their Confluence space

This year will mark my tenth anniversary of working in industry as a software engineer. That’s ten whole years of working in software development teams, all of which use various different methods to document projects, processes, and other relevant information within their organisation.

Many teams made heavy use of collaborative wikis to share information. Some produced elaborate design documents with diagrams, traceable requirements, risk analyses, and cost estimations, which were shared with others via network drives or cloud services. A few produced little bits of documentation from time to time, which would then be shared with others via Slack or READMEs. And there was also one team that hadn’t yet discovered the virtues of documentation and relied entirely on “artisanally crafted self-documenting code”.

Anecdotally, teams that spent little effort on documentation often spent a lot of time reinventing the wheel and panicking whenever a developer would inevitably leave for a new, better-paying opportunity elsewhere. On the other hand, teams that wrote everything down tended to be incredibly effective and efficient. This is why I strongly believe that teams should always be encouraged to write documentation and freely share knowledge amongst themselves.

I’ve had the opportunity to work with many different team collaboration tools throughout the years, such as BSCW, MediaWiki, TWiki (side note: This project has been dead for a while, so I won’t link to it.), SharePoint, Google Workspace and a handful of proprietary homegrown systems, but my favourite tool by far is Atlassian’s Confluence (side note: This article is not sponsored by Atlassian, but if someone from Atlassian is reading this: I could kind of use the money right now. 🫠). It’s free for up to 10 users and offers excellent integration with Atlassian’s other products, like JIRA.

In this article I’ll explain how I set up my workspaces (or simply “spaces”) in Confluence, but keep in mind that very few of the things I discuss here are specific to Confluence; you can use whatever tool you like.

Although technical documentation is the main reason why teams should use collaborative wikis, I personally believe a space isn’t really complete unless it also provides a place where the team can document their team agreements and meetings that they’ve held.

One of the most commonly heard complaints in software development teams is that there’s too little documentation or – in rare situations where documentation actually exists – that it’s outdated.

This is a hard problem that’s very to solve. Fact is that very few developers like writing documentation, and even fewer developers are good at it. It’s unlikely that this problem will magically resolve itself once you offer people a place and tool that makes it easier to write documentation. Nevertheless, I believe that there are ways to make documentation easier for both writers and readers.

I currently organise documentation in our space as follows:

	Troubleshooting	How-to	Explainer	Reference
System	1	2	3	4
Infrastructure	5	6	7	8
Development	9	10	11	12
Organisation	13	14	15	16

Documentation types

As you can see, I distinguish between four types of documentation (side note: These types are not mutually exclusive. For example, it’s perfectly fine if a how-to guide also includes a section that lists common issues.):

• Troubleshooting guides offer guidance for common problems.

• How-to guides provide step-by-step instructions for certain tasks.

• Explainers introduce the reader to a topic. For example, they may provide a high-level overview of a system’s architecture or an introductory explanation of the problem domain.

• Reference articles provide more in-depth information that’s useful for complex subjects or developers who need to get their hands dirty.

Most troubleshooting guides provide a lot of value, but cost almost no effort to write; some can even be as short as a single line, e.g. “Run docker image prune -a”. How-to guides require a bit more effort, while explainers and reference articles can take an hour or more to write.

If your team doesn’t have any written documentation yet, I suggest you start with the first two types and then slowly make your way towards the last two types.

Organising documentation

Documentation in a team space typically covers one of the following four topics:

• A system or project: this is what developers typically mean when they lament the lack of up-to-date documentation. Examples include UML sequence diagrams, descriptions of modules or business processes that have been implemented in a system.

• Infrastructure: documents in this category are more about the operations side of things, e.g. how deployments work or when and how the system has to be upgraded.

• Development: project-agnostic technical documentation, e.g. how to set up a development environment, how to use a debugger.

• Organisation: information about the organisation and its values, team procedures, perks, and benefits.

I’ve created sections for each of these topics in my Confluence space, but your team might not need all of them.

You want to make sure that everyone in your team is on the same page when it comes to expectations about processes, procedures, standards, and best practices.

Reserve a section within your space where team members can review what the team has agreed upon. Some typical examples include:

• The team’s definition of ready, which defines when a story or task is ready (i.e. clear enough) to be moved into a sprint;

• The team’s definition of done, which defines when a story or task is considered to be complete;

• Git merge strategies (squash, fast-forward?), branch name conventions, and commit naming conventions;

• How to proceed when a developer encounters some code that needs to be refactored while they are working on an unrelated task.

I’ll be honest with you: almost no one will read these team agreements, because usually every team member knows them by heart. The only two times when someone views them is right after they were written down and when a new person joins the team. The primary purpose of a section for team agreements is to foster discussion about what the team considers to be important and how it likes to work.

If a team spent an hour talking in a room without a clear agenda and none of the participants can summarise the meeting afterwards, did a meeting really take place? Arguably not, especially if that team feels the need to schedule a follow-up meeting.

This is why you should create an area within your space for meeting agendas and notes.

By publishing the agenda for a meeting beforehand, team members know what to expect and can prepare accordingly. Depending on your meeting culture, write access to the agenda can be limited to the chairperson or open to all team members.

Meeting notes not only help participants recall what was discussed, but also make it more likely that they follow up on action items, and are very helpful for team members who weren’t able to attend the meeting.

By the way, meeting notes don’t have to be very long or include every single thing that was said. A simple list of conclusions, decisions and action items (with an assignee and a deadline!) for each topic is good enough for most meetings.

Ideally, a team space should contain more than just the bare essentials. There are a few more things that are not strictly necessary, but certainly nice to have.

An RFC section provides a place for team members to freely share ideas for new features, technical designs, complex changes, analytical reports, process improvements, and so.

There need not be a fixed formats for RFCs (which are sometimes simply called proposals, ideas, or analyses). Most teams follow three guidelines when creating documents for new ideas:

• Each RFC has a unique identifier that can be used for communication within the team or with external stakeholders.

• Each RFC has one of the following statuses:

  • Draft: the document is a work in progress;

  • Review: the RFC is ready to be reviewed by the team. Others can comment on the RFC, ask questions, and suggest changes;

  • Accepted: the team has voted on the RFC and has decided to implement it;

  • Rejected: the team has voted on the RFC and has decided to not implement it (for now);

  • Final: primarily used for RFCs for which no voting is necessary.

• If an RFC is related to a JIRA issue, the issue number should be mentioned near the start of the document.

Many organisations have shared calendars or workforce management systems that can be used to check when employees are available, but such systems are not always easy to use.

This is why it might be a good idea to set up calendars in Confluence, where you could keep track of things like…

• Holidays: know when team members are out of office for longer periods so that work (or your own holiday) can be planned accordingly.

• Working from home: use a collaborative calendar to keep track of who will work from home in the coming period. This can help team members make more informed decisions about whether it’s worth the effort to commute to the office, e.g. when:

  • you discover that you’d be the only person at the office on Friday, so you decide to work from home on Friday;

  • your office doesn’t have enough desks to accommodate every worker, so you check the calendar to make sure there are enough desks available before you leave the house;

  • you’ve scheduled an appointment with your plumber next Thursday afternoon, and you want to remind your team that they can start lunch without you.

• Conferences/workshops/meetups: encourage team members to attend conferences, workshops and meetups; they might learn a thing or two!

Confluence is primarily meant to be used as a team workspace. But as a user you also have the ability to create your own space, which you can use for…

• A personal blog about experiences, lessons learnt, or other things that you might want to share about yourself;

• An accomplishments log that keeps track of all your achievements at work, so that you have a simple overview that you can show to your manager during the yearly performance review;

• A personal development plan that outlines your professional goals, and how and when you plan to achieve them.