Developing A Documentation Plan

In my professional experience as a technical writer, I've had the pleasure of working with several software development teams that have gone through highs and lows of successful product launches. The teams that included documentation as part of their planning process were often more successful than those who did not. This post will share a basic model for developing a documentation plan.

Planning Phase

During the planning phase, your technical writer should be present to identify any documentation needs and add a voice to the process so that end-user documentation can be included in the product life cycle. All too often, I've seen technical writers excluded from the process until the product is about 50-75% complete and then the project managers start asking questions like "Where is our documentation", "What is the status of our release notes?", or "Who is working on the documentation?" At this point, documentation will suffer as the technical writer must now go back through a bajillion documents, interview every developer and manager on the team to figure out what the minimal viable product (MVP) for documentation would be and do their best to reach that goal before release day.

Ideally, a development team would include you, the technical writer, in their planning process well before the midpoint of their project.

Setting Goals

Once the documentation set has been identified, you will need to collaborate with the subject matter experts (SMEs) to complete your doc tasks. During the initialization phase of this documentation project, you will need to complete the following items:

1. Identify who the primary and secondary SMEs are. Developers often take time off from work and you need to know who else can help contribute to this project while they are out so that you don’t get blocked or have a slowdown that could potentially delay the project.

2. Identify all the documentation components for MVP delivery and stretch goals.

3. Prioritize these doc goals so the team will know what you and they will need to focus on first.

4. Establish a timeline and due date for key components of the documentation.

5. Set documentation milestones. At what point should feature X be complete? When should feature Y be drafted? When should the release notes be published?

6. Set the paths of success and what failure would look like and include backup plans (e.g. what does 100%, 75%, and 50% complete look like).

7. Set up regular check-ins with the team to provide doc status updates, gather new information, and general project communication. This can be done as a standalone documentation meeting if the project is large or be included as an agenda item for the regular team meetings.

Project Maintenance

With the scoping and expectation phase complete, the rest of the project is a simple matter of gathering information, writing, and publishing content, right? In a perfect world, yes but we exist in a space where perfection is the enemy. In my experiences, senior technical writers should include the following in their regular process to properly communicate documentation status:

• Update associate project management tasks and timelines according to the doc project status and communicate these changes to key stakeholders. The frequency of this may be anywhere from daily to weekly depending on the size of the team, frequency of product updates, and other factors that would affect your doc plan.

• At key intervals, review the project roadmap to ensure that you and the team are hitting your milestones. Communicate any project slippage, task completion, and other general progress with key stakeholders. This communication should also include how the SMEs contributed so they can be recognized for their contributions.

• If the project is a long-term project, consider writing and publishing a monthly summary of all the completed work, where documentation energies are being spent, celebrate those who contribute to the documentation project, and highlight any interesting content traffic (e.g. wiki/web metrics, interesting search patterns, changes in viewership, etc.), and other bits of information that your team may find useful about the project.

• If you are not the primary writer…

• your team/company doesn’t have or enforce a style guide, you will need to build in some extra time to address documentation uniformity issues like tone, voice, and content structure.

• As new documents become available, ensure they are properly cross-linked with existing content and vice versa. Let the primary content creator know that you will and/or updated their content so there are no surprises.

• If a new document replaces an older one, if possible, let both documents co-exist for a brief time. Oftentimes, your users will need time to migrate off the old system and adapt to the new features. Add a banner or some sort of notice to the older document with a brief explanation, expected end of life date, and a link to the new documentation set. Sometimes you may be required to add a banner to the new document as well stating that this one replaces the older document. Include a link to the older one and a link to the release notes for further clarification. Once the older document has reached the end of life, set up a redirection feature in your wiki/web site to point to the new document and archive the older document from public view.

Documentation Days

What is "Doc Day"?

Doc Day is the opportunity for a team to take a break from their day to day routine to write crucial or necessary documentation.

Abstract

"Efficiency is doing things right; effectiveness is doing the right things." - Peter Drucker

The purpose of Doc Day is to provide an opportunity for a team (or department) to take a break from their day to day routine and to either gather and organize documents, write new documentation, update or archive old documents, or to tackle long overdue documentation tasks.

The most common problem technical writers face is huge documentation backlogs and regular requests from both users and the teams to create or maintain documentation. While some roles of a technical writer is to become a subject matter expert, often time it is very difficult given time constraints, shifting schedule deadlines, and the consumer/tech writer ratio (at one point, I worked for a company that had a ratio of 2400 to 3).

While there are many methods to complete day to day documentation tasks, bigger projects and opportunities for the company to be more efficient can linger on and on and sometimes sit too long on the back-burner. Consider this scenario: John needs to write a document about a widget. John searches the company's internal documentation system for two looking information he needs. For the most part, he may find fragments here and there but not enough to go on. At this point, John resorts to information from his notes from previous team meetings (another hour spent researching). John knows that Adam (an engineer on the project) mentioned a point about the widget. John meets with Adam to gather information about the widget over the course of an hour only to discover that he wrote the tests for the widget and his information is too low level for the documentation. He informs John that Mary was the primary engineer assigned to develop the widget. Both John and Adam meet with Mary to get detailed information about how the widget was designed to work (or not). After a brief introduction to the task at hand, Mary invites yet another engineer (Po) to this meeting. Mary then explains to three different people the overview and main features with both Adam and Po asking questions and getting into minor debates every so often over the course of an hour. If Mary would have been given the time to write an overview document explaining the purpose of the widget, listed the features, and current bugs, she could have saved John five hours, Adam two hours, and Mary and Po one hour of searching, discussing, and meeting. Total time spent researching and sharing: 9 hours. Time Mary could have written the overview: 1 hour.

In this scenario, we see a rather bad use of time for everyone involved (though I'm not going to knock the value of personal interactions or connections). Engaging in a regularly scheduled document event, the engineers can spend an entire day writing new guides or refreshing documentation and possibly archive outdated documents that the team, their manager, and their consumers deem worthy of the Doc Day. The technical writer acts as a facilitator during this event providing support (both technical and writing related), hosts meetings prior to the event discussing the goals and assignments, writing and sharing templates with the team, and making oneself available throughout the event for answering any issues that arise. At the end of the day, the Doc Day concludes with a meeting where the participating members of the event meet, share their documents and snippets of their documents with the team, enjoy some refreshments, and (optional) receive an merit of honor (small gift or token of esteem). The participating members would each vote on the presentation, completeness of the documentation assigned, and any other criteria set by the event.

In my experience, everyone who ever participated in a Doc Day event, planned their time around the event to dedicate themselves solely to documentation, generally enjoyed the time while writing, looked forward to the next Doc Day event, and was thankful for everyone sharing their documentation effort at the end of the day. The team then reviewed the documents to learn more about what was written and applied any nuggets of knowledge to their own respective projects. The technical writer and the writer's manager is happy because some of their backlog and/or feature requests have been resolved.

How Does It Work?

The lead of a team designates a day (blessed from management) to work purely on documentation for one day. The team is given a notice of at least a week in advance so that they can submit topics to be documented.

Team members submit a list of items that can be documented in less than a day to their lead. The lead then goes through the list and makes the final list of topics to be written. Topics may be assigned to the submitted or to someone else who has deeper knowledge of the proposed topic. Topics should be able to be completed in less than one working day (approximately 7 man hours). Team members may write more than one topic if the topics can be completed by the end of the day.

Frequency

Ideally, Doc Days should occur every quarter but at the very least, once a year per team.

What Do We Write?

Anything that should be documented but currently isn't. Here are a few examples:

• A procedure that needs documentation
• Missing documentation from API modules
• Cross-training documents
• Instructional guides on various technologies
• Revising outdated documentation
• Anything that can be beneficial to the team, company-at-large, or our customers

The documentation can be either internal or externally facing.

Support

You friendly neighborhood tech writer is more than happy to help out with any writing issues you may encounter during your Doc Day assignment. Spell-check, grammar correction, technical issues with Confluence (wiki), and image capture/manipulation are a few services your tech writer is happy to assist you with. If English isn't your first language (or even if it is) and you're working on a document that will be public facing, please have someone review it before publishing it.

Doc Day Event

Prior to the Doc Day, the technical writer will set up a wiki page with all the assigned topics, writers, and links to the pages to be documented. This page will then be shared with the team the day before the Doc Day.

The day before the Doc Day, the team meets to go over their assignment topics and answer any and all questions about the Doc Day. The technical writer should be present to assist in answering any questions.

On the day of the event:

1. Team members start their day by reviewing their writing assignment(s).
2. Team members write their assigned topic(s).
3. Once a topic has been written, it can be submitted to the tech writer or team lead for review.
4. At the end of the day, the team meets for an hour to review the completed documents and vote on the best presentation and topic. The writer with the most votes wins a super cool prize.
   1. The doc review may or may not include snacks and liquid refreshments (of the adult beverage type).
   2. The prize can be anything: a badge of honor, gift card to Amazon (something of monetary value), or a trophy that is passed along from time to time.

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.