#topic/content-management #max/lessons-learned

Master Guide approach to support team user guides

Business Problem

In 2014 shortly after the team was formed, we had little documentation, except for that which was created for a migration project. Even though those guides contained useful information, their purpose wasn’t to teach. For example, to edit a Rubric, you’d have to open a doc called “Migrating Rubrics” and skim for the information needed.

The guides were unclear for troubleshooting, resulting in duplicate issues and questions. External products were not well-documented by the vendor and internal products were not documented at all. To address this, a teammate and I created a scenario-based documentation library, collaborating on email templates and troubleshooting tips.

By 2017, the team had grown and the library needed to be reorganized for new members to access vital information and keep content accurate.

The Solution

We consolidated information into “master” guides for each product, creating a one-stop-shop for users so they wouldn’t have to sort through 75+ individual guides to find their answers. These guides were under 50 pages, well-managed, and included scenarios to improve efficiency in resolving tickets. Users were expected to use built-in features in Microsoft Word to navigate and find information.

Users could:

• Find information easily using a structured Table of Contents
• Ctrl+F to keyword search within the guide
• Benefit from each other’s knowledge (sharing is caring!)

Challenges

By 2019, the guides had grown longer. As a team we had compiled a comprehensive repository of resources covering technical issues and helpful process details.

• Disorganized headers made the Table of Contents less useful.
• Guides lacked ownership, resulting in inconsistencies in formatting, style, language, and tone.
• Content was added without long-term consideration, making it difficult to apply to multiple scenarios. It was presented in specific scenarios implying that those are the only scenarios you’d use those instructions, which isn’t true.
• Guides primarily focused on process and troubleshooting, lacking information on product navigation and usage, causing complaints from newer team members.

Solutions

To address these challenges, I took ownership of editing the guides. Equipped with technical writing professional development, I aimed to improve readability, navigation, and usefulness for our audience. Through needs analysis workshops, we made changes to the first full master guide revision, including:

• Added color-coded “note” boxes with helpful hints & troubleshooting tips
• Updated the organization, separating background information from instructions (easier to skip to what you need)
• Accessibility considerations on supplementary media, wording, and formatting
• Given feedback, product instructions were added to explain basic functionality
• All content was revised/updated to a consistent tone and edited for clarity
• Though scenario-specific troubleshooting was still included, the guides focused more on process and product instructions
• Added links to other guides (everything is related) and content references/breadcrumbs
• Added glossaries

First Revision Timeline

Unfortunately, the guides became outdated quickly and were a maintenance nightmare, taking 3-5 months to fully revise. Without constant support and upkeep of documentation from the team, the “system” of master guides fell apart and became the responsibility of one person.

*This time period had about a month of interruption due to holidays and vacation.

Reflection

At the onset and with what we had at the time, the master guides were a great idea! They served the purpose for which we needed them: to bring all of the information together in one place.

The master guides were my first foray into managing process and product documentation, providing me with practical lessons that will be applied to future writing.

Lesson: “Completeness” doesn’t mean including everything.

Long guides (some almost 150 pages) became less useful and added too much time to troubleshooting, leading team members to prefer resolving tickets without guide help. Lessons learned include content relevance, guide length, and readability.

Lesson: You will, in fact, need to revise at some point!

I focused on delivering content effectively, not considering long-term maintenance. Establish a timeline for maintenance cycles.

Lesson: Discuss documentation roles and expectations with the team.

The guide system lacked maintenance from the team due to unclear roles/expectations. Communicate expectations early and clearly, provide guidance for consistency among collaborators.

Lesson: Discuss new responsibilities with the boss to avoid overwhelming workload.

Taking on the task of updating guides led to others assuming it was solely my responsibility to maintain the guides. Since this was never part of my job description, it quickly became unmanageable and difficult to prioritize.

Lesson: Analyze the needs of your entire audience.

The guides were tailored to individual user needs given who was on the team at that time, neglecting the team (as a whole) and future versions of it. Guides have a primary and secondary audience (current and future team members, respectively), but only the primary audience was considered, resulting in confusion for new team members.

Lesson: Ensure everyone has the same information and avoid assumptions.

Assuming users knew how to use Microsoft Word’s Navigation pane led to confusion. Though they were using keyword searches, they didn’t know how to do it properly (must be exact match, similar words will not result).

Sunset and Recommendation

New team members found the guides too dense. Without proper training resources and onboarding, they were left in an endless loop trying to locate information they weren’t yet familiar with. The guides were structured for people who knew what they were looking for. We eventually had to start training on how to use the guides.

The team’s purpose changed at the end of 2022, making most docs inaccurate regarding the team’s scope. Because of this, the guides will require major revisions, so we’ll take the opportunity to replace the master guides with a new AEM-based documentation solution.

The migration in late 2023 will bring significant guide improvements:

• Links to vendor guides to reduce content maintenance
• Reusable content
• Comment on interdependencies for complete and accurate updates
• Focus on accessibility with built-in features
• Potential for automation in many areas (e.g., if a page is moved, links to that content will auto-update)
• Feedback mechanism
• Standardized workflows for writing, editing, and publishing
• A SME review process to ensure content added is accurate and complete
• Clear expectations on who is responsible for updating what, and when
• Template standards to reduce formatting inconsistencies

Though as writers we are excited to share the knowledge, it turns out most people don’t want to use documentation if they can avoid it. The guide must provide the information they need immediately; they are uninterested in browsing/reading to find what they are looking for.

My recommendations to anyone considering this approach:

• Analyze your audience needs and couple that with documentation best practices. Readers do not always know what they need or how to format things. General writing guidelines fill in the blanks.
• Create user stories. Don’t limit your research to what information they need, include how they will get to it. This will help with structuring and outlining.
• Collect feedback from the guide users before making major changes.
• A master guide delivered in Microsoft Word is only useful if it’s 50 pages or less. A longer doc starts to feel like a 1-pager of excessive length.
• Link out to supplementary information and vendor guides instead of requiring yourself to document instructions that are available elsewhere. This will keep the length and maintenance workload down.

Created: 6/10/23