How to Create a Documentation Structure that Works for the Whole Team
Comment
How to Create a Documentation Structure That Works for the Whole Team
Great public documentation helps you build a base of happy, successful, and self-sufficient users. What's more, great documentation can lead to a more productive and aligned product team, especially when everyone is involved in its creation.
But teams tend to forget that documentation isn't just about the content itself; how you choose to structure that content will have an even bigger impact on both your users and the team members who write and contribute to the docs.
So how do you create and maintain well-structured documentation? This post outlines the detailed steps you should take to ensure that your team is putting its best documentation forward.
The Best Documentation is Written as a Team
Even if you're lucky enough to have a team of tech writers on hand, documentation shouldn't be written in isolation. To produce the best, most accurate documentation for your users, you need to concisely deliver product knowledge that is continuously collected from and used by various team roles. This includes:
- Developers and UX designers who work directly on the product and steer its development, design, and specifications.
- Sales and marketing teams who use the information to drive awareness and enable leads during consideration and evaluation phases.
- Customer success and support agents who rely on the documentation to deflect support inquires, answer questions consistently and accurately, and provide feedback when the documentation is unclear or outdated.
So you need a tool where everyone on the team can access, contribute to, and refine the documentation – regardless of their role.
Confluence offers a collaborative solution for documentation. Confluence is used for everything from internal communication to project planning and management, making it the single source of truth for collecting your team's knowledge. This makes it the perfect place for your team to author and manage your product documentation, and even deliver it directly to your users as a public help center or knowledge base.
With your collaborative tool at hand and your team ready to author and contribute to your docs, your next step is to define a structure for your documentation.
Structure Matters Most
Whether your team is about to launch an exciting new product and you're starting the docs from scratch, or you're simply revising an existing documentation set, start with the structure. This is one of the first impressions you leave on your users, and this experience will reflect on their ability to be successful with your product – so it's worth getting right!
At a very high level, your documentation should be:
- Easy to navigate
- Categorized in a logical way
- Offer quick and easy access to the most relevant information to users
But before getting to this point, many teams run into the same problems: Contributors don't follow set guidelines for content or design, new articles or updates don't fit into the existing structure, or the team is unable to decide on the best approach to structuring topics.
Defining the structure ahead of time will help avoid these problems by creating consistency in writing and format, enforcing basic guidelines around design structures, and providing a more unified experience for your end users so they can find information and understand its meaning with ease.
Multiple Approaches to Structuring Your Documentation Topics
How do you decide what to structure by? There are a few approaches your team could take to documenting your product:
| Approach | Description | Example Articles |
|---|---|---|
| The Product Structure | Take a feature-first approach by documenting the major features of your product. | How to Use the Form Builder |
| The User Interface | Document your product based on its primary interaction elements and screens. | A Tour of the Activity Log Screen |
| User Tasks | Explain what actions your users should take in order to perform a task and achieve a specific goal. | How to Customize and Brand the Help Center Theme |
| End User Role | Describe tasks and features based on the goals and perspectives of various end users of your product. | Administrator's Guide for Installation |
One structure doesn’t fit all and in most cases your documentation will contain a blend of multiple approaches. So decide as a team as to which approaches will work best for your broader user base. Analyze user journeys, customer feedback, and onboarding flows to help guide this decision.
If you're using the right tool, you won't be locked into a single approach. With a flexible documentation tool like Confluence, it's easy to add and edit articles and change topic structures.
Your team can quickly adapt and deliver your documentation based on different customer requirements, that includes publishing to the web and exporting as customized PDF or Word documents. If it's PDFs you choose to export, you'll find plenty of downloadable templates on the Template Library.
Define Topic Types
Once you've settled on your structure, it's time to establish some topic types to help writers decide which types of content to write and how. Topic types are a way of breaking your content down into organized blocks and classifying the various articles your team will write. Some common topic types include:
- Concept: Concept articles describe a concept in depth, typically a linear page
- Task: Lists the steps to complete a user action, typically includes a numbered list
- Reference: Provides additional information related to a concept, typically a tabular page
- Troubleshooting: Describes an issue and lists the steps needed to solve the issue
The best practice is to design a guideline for each type and then turn them into templates. These templates act as recipes for your team to help decide on a topic and get started quickly whenever they need to contribute to the docs.
Templates also help enforce content structures and designs within your articles, meaning anyone in your team can confidently contribute the right information without doubling the work for you as a writer or manager.
Confluence enables you to create powerful interactive templates, complete with instructional text, template variables, and macros that help you add extra functionality and include dynamic content.
Better Structure, Better Docs
With these steps established and your team now involved, how do you measure success? When your documentation structure is effective:
- Users are able to find information quickly and understand its meaning with ease
- Contributors know what they need to share and how
- The team can access and use the documentation to support their role in the team – whether that's to deflect support tickets, write marketing messaging, or answer complex questions from sales prospects
For writers or managers, you'll also see a noticeable difference: guidelines are easier to enforce, format is more consistent, and you'll notice that your team actually wants to contribute to the docs because the process is less time-consuming and they benefit from the end result.
Ready to Get Started?
Many teams are already using Confluence to successfully author and structure their documentation, along with Scroll Viewport to deliver it directly to their users as a beautiful, customized help center.
