Rohini Garde, VMware
August 15, 2020

In a recent company All-Hands meeting, VMware CEO, Pat Gelsinger, said, “Let’s move VMware faster to the future.” The phrase “faster to the future” got my immediate attention.

After the meeting, I started thinking about the phrase and wondered, “As a technical writer, what can I do to support this company goal?  What could be my contribution in helping VMware move faster to the future? “Can I document faster to the future”?

Well, as a technical writer for around 15 years, I always documented products after looking at the product, using, and testing the features myself. I always like to find out how each feature works, what might fail, or how to verify that the configuration worked. All the first-hand testing helped me write more accurate technical content.

But in this typical documentation development process, understanding a feature requires waiting for others to complete their work first. To begin actual documentation about the product or a feature, development must first be code complete. So, my actual documentation development starts late in the Software Development Life Cycle. I had to squeeze in my tasks near the end of the development life cycle and scramble to test the feature, write accurate technical content, and get the documentation reviews done before the GA date.

In this scenario, how can I support faster to the future?

The key factor could be getting involved and collaborating as a writer early in the process.

I recently had an opportunity to work on a brand-new product at VMware where technical writers are part of the UX team. UX designers and writers collaborate and work as one team. Everything in the product is driven by the UX team. UX designers create detailed workflows, wireframes, and mock-ups based on discussions with product managers and engineering teams.

The UX design team completes thorough user research to develop personas and a user journey map that helps identify the needs, behaviors, and goals of the users. The workflows provide the path that the user must follow to be successful completing a certain task. For example, workflows are developed for installation, configuring a certain feature, upgrading the product. UX designers identify the happy path, failure cases, and so on.

Different workflows, wireframes, and mock-ups help me understand how users will proceed to use the product or feature. For example:

  • Prerequisites to perform a task
  • The installation or configuration path
  • The possible error messages and component in which to look for resolution
  • After the product or feature is configured, what is the first screen the user sees
  • How do users proceed, and so on

When the mock-ups and wireframes for a feature were ready from the UX designers, the engineering team started developing the feature, and I started documenting the feature in parallel. These are the steps that I took to achieve the first draft quickly:

  1. Pair with the lead UX designer for each feature and acquire the latest workflows, wireframes, and mock-ups. Also study the functional specs, architecture or design documents, or any available material.
  2. Participate in UX research to know your audience and the different personas involved.
  3. Access the existing User Interface and visualize the workflows based on the mock-ups. Create a detailed table of content (TOC) for the guide.
  4. Work with the UX, Product Managers (PM), and Engineering Managers to validate the TOC and clarify any queries.
  5. Develop the first draft. After the code is complete, look at the actual features to make any adjustments to the draft and get the topics reviewed.

These steps, along with the early collaboration, helped me keep pace with the UX and engineering teams and develop quality documentation.

That’s what I would call “documenting faster to the future”!!