There’s a lot to be said about why your team needs documentation and how to build engaging, user-friendly documentation.
But what does that really mean in the context of a software engineering team, especially one that has embraced an Agile work style?
There are three types of documentation that every software development team needs in order to function effectively and avoid future roadblocks — documentation of ongoing discussions, the decision-making process, and technical information.
This structure for documentation captures not only the system and process information you need to do your job, but also the implicit institutional knowledge that every team relies on, whether they realize it or not.
Let’s dive into each type to explore why they are important and how they contribute to your team’s productivity.
Documenting Ongoing Discussions
When was the last time you or a colleague had an important discussion about the direction of a project over email, messaging, or a verbal conversation?
These instinctive ways of communicating with coworkers are natural, but they may cause later issues that are difficult to anticipate at the moment. For example, what happens when a conversation is misremembered or misinterpreted, and someone who wasn’t involved in the conversation needs context about what was discussed?
Email threads and messaging app conversations can be difficult to track down, whiteboard sketches may have been erased before anyone remembered to snap a picture, user stories don’t always tell the full story, and of course, there’s no way to go back and re-listen to a verbal conversation.
That’s why it’s important to make sure that your team is documenting ongoing discussions that may have an impact on future decisions. That doesn’t mean to forgo natural conversations in favor of written communication — that interaction is important, especially for Agile teams who highly value collaboration and conversation.
So, how do you document ongoing discussions?
This might start with something as simple as keeping diligent meeting notes. Make sure to do this in a shared document with everyone present at the meeting. Record who was present for the conversation and include dates as well as links to any other helpful context.
Back to topDocumenting Your Decision-Making Process
The process of documenting ongoing discussions can naturally capture much of the context behind important decisions, but it’s also valuable to clearly and intentionally document your team’s decision-making process.
Sometimes, especially during long ongoing projects, decisions must be made that alter the course of the project significantly. Recording the process behind these decisions can help avoid confusion, frustration, or having to revisit the same questions later.
When putting together decision-making documentation such as an architecture decision record, you should record who made the decision, who needs to be informed about the decision, and all the alternative options that were considered.
However, it’s also important to include further context about why the decision was made, not just the details of it. What are the risks and potential consequences of making such a decision?
What’s the best way to gather all this information? Atlassian’s decision template for Confluence can be a helpful place to start. It includes a framework for identifying stakeholders as well as reporting on the status of the decision after it is implemented.
Back to topDocumenting Technical Information
This is the type of documentation that you are most likely to think of right away when you consider the meaning of documentation. Informational documentation covers technical information such as architecture, processes, network and software topology, and more — anything you need to know in order to understand how the system works.
This might also include details about application components and dependencies that are captured in your SBOM.
Informational documentation may cover information that your team already knows, so creating it might feel like a low priority. However, it’s most helpful when onboarding new team members in order to get them up to speed quickly, with less of a burden on the existing team members.
Plus, documenting technical information helps you avoid the problem of encountering serious knowledge gaps when a member of your team who holds a lot of niche product knowledge leaves the organization.
Informational documentation also helps you collaborate with stakeholders outside of your team that may have varying levels of technical expertise. For example, you could simply show an executive team a visual representation of an application’s structure to explain your vision and progress, which will be easier for them to understand than a completely verbal explanation.
When you are putting together informational documentation, creating some of the essential application architecture diagrams might be a good place to start.
Back to topLearn More About Building Documentation
Now you have a baseline for what types of documentation are necessary and direction for creating them. But what’s next?
We have plenty of additional resources for building great documentation that your team will actually use — and a few specifically for doing so in Confluence.
- Software Architecture Documentation: Common Mistakes & Best Practices
- Why Build Confluence Documentation?
- 4 Ways to Supercharge Your Confluence Documentation
- Creating Confluence Pages Your Team Will Actually Read
- The Top 5 Apps for Your Confluence Knowledge Base
Gliffy is the perfect helper for creating technical documentation because it allows you to create detailed software engineering diagrams directly in Confluence with no extra logins or imports. You can try it free today!