Documentation standards to live by

The standards you follow will vary according to the type of documentation you are creating. Here are a few common types , as well as suggestions on templates you can use to establish your standards.

Any project will go more smoothly when everyone involved is on the same page. All team members on a project need a single source of truth that they can refer to at any time. Without a documented project plan, team members can lose sight of the big picture and end up wasting time.

To speed up and standardize project documentation, you can use this template by Confluence. It will ensure that you consistently capture key information about every project.

Do your team members lose time because they have to constantly explain to others how to do things? Or have you ever found yourself scrambling when the one person who knew how to do a key task or process was out of the office?

These scenarios point to the importance of how-to documentation. Basically, anything that your team members do repeatedly needs to be documented in a way that enables anyone on your team to complete that task or process.

How-to documentation is more effective, not to mention easier to create, when you have established standards. Again, this is where a template comes in handy. For example, Confluence's template for how-to articles gives you a formula for process documentation.

Documentation for software and other technical products can explain how the product works, how to use it, how it was created, and how it's put together.

Software teams may refer to documentation when talking about product requirements, release notes, or design specs. Technical teams may use documentation to detail code, APIs, and record their software development processes.

Technical documentation tends to be lengthy, detailed, and updated frequently, so it's especially important to have the right tools to ensure accuracy and save time. For example, you can use existing templates in Confluence or create your own. Confluence also has macros that make it easy to update or reuse text.

No matter what type of documentation you are creating, there are a few key skills that will ensure that your work meets your documentation standards and is helpful to users.

• Organization. Knowing the information you want to document is one thing. Presenting it in an easy-to-follow way is quite another. Beyond organizing the information in a logical order, it's also important to use elements like section headers and bulleted lists to guide the users of your documentation.
• Clarity. Clear, easy-to-understand documentation requires choosing just the right level of detail. Too little information is confusing, but so is too much. Other ways to improve the clarity of your documentation include being meticulous with your grammar, avoiding jargon, and choosing specific words over vague ones (like "often").
• Consistency. Paying attention to consistency is one of the most helpful things you can do for anyone who'll be using your documentation. For example, a user will have an easier time following your how-to documentation if it's written in the same way as other how-to documents at your organization.

Establishing standards doesn't just help you create better documentation. It also helps you distribute that documentation more effectively.

To be useful, documentation has to be accessible to your entire team. You don't want team members keeping important information on their individual hard drives. And you don't want them to have to rely on a single printed copy that's hidden away in a random filing cabinet. Situations like these lead to confusion and inefficiency.

For example, team members using different versions of documentation might have miscommunications or accidentally create extra work for each other. Or a person who's working remotely might need to access documentation that exists only as a physical copy at the office.

You can avoid these problems by standardizing how you store and distribute documentation. It works best to have a centralized repository: a single place where everyone knows to look for the most up-to-date information. But beyond just getting everything in one place, you also have to make it easy for people to find what they are looking for when they get there.

For us at Atlassian, that centralized repository is Confluence. Features like powerful search, structured page trees, and page archive ensure content is easy to find, within reach, and up to date.

In Confluence, every team or project has a space to organize their related documentation. They can create a hierarchy of pages to keep all the information organized and visible from the page tree. Employees can watch spaces or sub-pages that they care about in order to get updated when the content changes. To distribute a particular space or page, you can use the share button or comment on a page and tag other team members. All open pages in Confluence are searchable by other employees and they can use filters to narrow their search by creator, publish date, or space.

Just as your individual pieces of documentation need consistent updates, so does your system of filing and organizing documentation. So don't forget to establish your standards here, too. How often do you need to revisit and tidy up your document filing? Go ahead and set aside those times on the calendar.

Now that you have an overview of documentation standards, you can start developing or revising guidelines for the types of documentation your team needs. The time you invest in setting these standards will help you create documentation faster and make that documentation more useful for your team.