Amanda Barfield, VMware
June 15, 2020

Prior to working at VMware as a Senior Technical Writer, most of my experience was working with start-up companies where I created a solid foundation for their documentation to grow and scale with them. One of the many things I’ve learned from VMware is how essential it is to incorporate Enterprise-Grade documentation reviews in each release cycle, regardless of company size or geographic differences. Working at a start-up is exciting, it’s thrilling, and there’s constant action, with the opportunity to build something from the ground up. The high agility allows engineering to release new features, updates, and fixes at the flip of a coin. As a Technical Writer, my biggest struggle was trying to figure out how to keep the documentation accurate and helpful to our customers, while still flowing with the agility of the start-up environment; I believe VMware Workspace ONE UEM has found a solution.

What is Project Think Tank?

Project Think Tank is a collaborative project involving GSS, R&D, and IX. Subject Matter Experts (SMEs) work together to ensure our key documentations are as accurate as possible. The initiative started small but has grown to include 18 documents with 46 participants. Based on high customer searches, page views, and the importance of the content, new documents get added each cycle. The goal is for all documents to be included in PTT. The PTT participants include Technical Writers, IX Managers, System Test Managers, Program Managers, Engineers, Senior Design Architects, and more. Each on-premises release, a line-by-line review is performed to ensure accuracy and usability.

Workflow

The PTT initiative was designed to fit seamlessly with the current VMware Workspace ONE UEM on-premises release cycle. We start PTT at the same time the on-premises release cycle begins and continue all the way to the general availability release. Learn more about the steps we take to ensure our PTT process is as efficient and useful as possible.

  1. Mandatory PTT kick-off meeting is scheduled by PTT Leads (Introduces any newly included documents, who is working on review, deadlines, and answer any questions)
  2. Writers link to documentation in a dedicated PTT JIRA Task
  3. Reviewer creates a bug assigned to the writer for any updates
  4. Once updates have been made, the writer posts an internal document link for review and assigns the bug back to the reviewer.
  5. The reviewer then approves the change, and the bug is closed

The PTT Advantage

What gives PTT an edge over traditional review processes is having multiple teams involved with the sole purpose of enhancing the entire document; not just fixing a customer issue or updating a version number. These comprehensive reviews include looking for items such as,

  • updates to existing features
  • compatibility changes
  • use case scenario additions
  • re-organization suggestions
  • usability enhancements
  • addition of adding concept graphics

The earlier you catch documentation issues in the on-premises release cycle and get into the flow, the easier it is to sustain. After a few cycles, it becomes part of the everyday workflow, allowing the documentation to grow with the product and remain accurate. The idea is that the number of internal bugs filed per document decreases with each PTT cycle. One thing to consider when looking at the data of internal bugs is the length of time between each release. A good example is shown in the graph below of the number of internal bugs filed during PTT for our VMware Workspace ONE UEM Tunnel Guide. We chose the tunnel guide because it is a high-profile guide used by our customers frequently. As you can see, the numbers are generally decreasing, but there are variations. Releases 1904 and 1905 were within a few months of each other, so 1905 had very few bugs; on the other hand, 1905 and 1907 were farther apart, resulting in a higher bug count. Even though 1907 had more bugs than 1905, it is still drastically less than in 1903.

While seeing the number of internal bugs decrease is a good overall indicator of success, also look at the importance of those bugs. For example, they are not just spelling and grammar updates, they are adding valuable use cases, concept graphic ideas, and more.

Why is it so Important for Start-up Companies?

This type of review is especially important in the fast-paced culture of a growing start-up where most employees perform multiple jobs and wear many hats because it allows, and almost forces, joint collaboration and constant communication between teams, regardless of geographical differences, job titles, and hierarchy. Everyone joins in one initiative to boost documentation accuracy and to enhance customer trust in their knowledge of their own product.

Start-up companies have a plethora of costs, and a massive support team usually isn’t first on the list. Having superior documentation allows customers to help themselves and builds a crucial layer of trust between you and your customer, not to mention your industry.

Key Points

  • Customer self-resolution
  • Deflected tickets
  • Customer trust & reliability

Customer self-resolution is a hot topic and is particularly relevant for start-up companies with a smaller staff count. Companies are realizing the value of good documentation and that it can serve as a barrier between their staff and unnecessary customer support tickets by deflecting them to self-help documentation. This greatly reduces the workload of support staff and equally increases customer satisfaction.

It is difficult to measure the success of an initiative like this because success means measuring a lack of something; fewer customer bugs are filed, and more customers are using self-help to exclusively help solve their issues. Even though it is hard to exclusively measure, we have seen a reduction in customer filed bugs for PTT documents in comparison to before the initiative started. We also have better internal relationships with people across multiple departments which has led to enhanced communication even outside PTT.

Conclusion

Industries are constantly changing, products get deprecated, and requirements evolve; having a diverse document review team of both support and backend teams helps create the necessary coverage to ensure all angles of a document are reviewed. Getting multiple teams involved in the documentation process not only creates more accurate content, but it frees up writers to focus on big picture documentation issues. Instead of just copying information they’ve tracked down, writers become Content Strategists — focusing on how to best utilize the technical content.

In conclusion, your company’s documentation is a reflection on all those who maintain it. If the documentation is poor, it reflects onto the company and will lead to an increase of unnecessary escalations and employee frustration. You don’t have to be an Enterprise level company to utilize an Enterprise-Grade review process. Your customers and staff will thank you!