Sustainable Documentation in Confluence

Maintaining documentation in Confluence can be challenging at times (especially if you work for a company that produces hundreds or thousands of pages a month). This post provides some tips on how provide for sustainable documentation in Confluence.

• Proper page names - this should go without saying. 
• Leaving comments when editing a page (even minor edits like fixing typos). This will help with reviewing the page (history) when an issue arises in the future 
• Linking is important (internally and to some extent externally). Confluence maintains links (intra and extra-space) automatically but doesn't valid or attempt to help the user when an external link is broken. If the external link is important, consider copying the content from the source and provide credit on the page. This wades into some grey areas that will need to be handled on a document-by-document basis (unless we have a company policy that provides guidelines as such). 
• Labeling - helps with search results and potential documentation groupings. Use simple concise terms, avoid plurals and verbs, and try to limit to no more than three or four terms. 
• Document hierarchies - Navigation my be king in documentation but it's not the "be-all end-all" solution. Keep the end user in mind. Topics must flow based on a simple logic or whatever logic your company deems necessary. 
• Minimal use of macros. Plugins come and go all the time (based on popularity and yearly budget). 
• Use page comments where necessary. If someone leaves a comment on a page that calls for action, do it, reply to the comment as such, and then remove the comments. It doesn't look good on us to leave years old comment on a page. Visitors will see the comment and may think the document is out of date. 
• Pictures are worth a thousand words or minus a thousand words if they are sorely out of date. Try to use generic images where possible in your general documentation. Product version-specific imagery should be generally avoided unless it is tied to a release. The same is true of videos. Also, Confluence isn't a media hosting service and file attachments are limited to 25mb (default). Videos attachments should avoided categorically. I have several stories (fun, sad, and problematic) about this topic. 
• On the topic if images, confirm that all images are properly attached to the target wiki page. While one can attach images from multiple sources (other wiki pages (complex topic), external sites, other servers, etc), you will run into publication issues if the images are not found within the Confluence server. 
• Using the search engine to suss out outliers and commonly searched terms. Try to do this on a quarterly basis to see where your users are going and look for potential gaps in your documentation. This creeps into using and reviewing analytic data to draw a bigger and clearly picture. 
• Try to find "Documentation Champions". DCs will be your ally in keeping the docs current and concise while notifying you of any weeds popping up their doc garden. Encourage them to contribute freely and review their work for minor issues (verbiage, typos, messaging, language issues, etc.). DCs will be your best resource to get other invested in the documentation when they feel welcomed, encouraged, and rewarded. 
• If some people on your team have not started using Confluence for documentation (a.k.a. "squeaky wheels"), engaged them. Ask why they haven't adopted Confluence. The reasons can be numerous but most likely, at least from my experiences, it because they don't want to "learn another program", "they're too busy to ...", or "I like my current workflow to document". Look for the pain points and point out that we are using Confluence as the main source of documentation. Does the squeaky wheel really want to be left behind? 
• Try to schedule regular doc reviews (annually would be nice). It's difficult to get the team engaged on this one but if one has the time to show the value of having fresh and current documentation, then the product manager should take this task up regularly. This will help prevent documentation overload. 
• Don't be afraid to archive documents in a separate non-searchable space. This will have to be negationed with you and your team. Confluence has the option to make a space searchable or not. All spaces are searchable by default but when a space is marked as non-searchable, the documents found within it will not show up in a search result unless requested in the search options. There are tools out that can automate this process but you'll have to see if we have the budget for that plugin. 
• Rely Confluence's version control for documents and attachments. When in doubt, check the page history and revert as necessary. 
• Use restrictions lightly. If you need to draft something that isn't ready for prime time, consider restricting the single page or parent page if the page count is under a dozen or so. If you have a need for restricting an entire space for whatever reason, do so but don't openly mention the restricted space in meetings. This will provide an air of mystery when there is none (hopefully). 
• Don't over-complicate permissions for individuals or groups. Keep it as simple as possible. You don't want to spend time managing permissions do you? 
• Refuse to provide people with PDFs of a document. Printing a page is rather wasteful if they have access to the wiki. While Confluence natively supports the option to export a document to PDF, don't go out of your way to advertise this feature. 
• If a page is out of date, look at who the original creator is and who last edited it. Contact those individuals and ask for clarity on the topic. Often time, these individuals (sometimes one in the same) will be happy to help you out.
• Templates are golden. If your users are afraid to create a new blank page, give them a template and ask them to simply fill in the blanks. This helps new Confluences get started with Confluence, gain confidence with Confluence, and helps you maintain order (somewhat) in how your content is formed.