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:
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.
Identify all the documentation components for MVP delivery and stretch goals.
Prioritize these doc goals so the team will know what you and they will need to focus on first.
Establish a timeline and due date for key components of the documentation.
Set documentation milestones. At what point should feature X be complete? When should feature Y be drafted? When should the release notes be published?
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).
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.
