The Product is Docs: Writing technical documentation in a product development group
The Product is Docs: Writing technical documentation in a product development group
Christopher Gales and Splunk Documentation Team
JoAnn Hackos’s pioneering book Managing your Documentation Projects is still a keystone
We wanted a book that covered the reality of developing technical documentation in a fast-moving product development organization, what makes a technical writer exceptional? Resourcefulness and eagerness are the key. When you screen tech writer candidates, look for a real appetite for discovery. The job, fundamentally, isn’t about writing or learning technology. It’s a relationship business, more like investigative journalism than anything else. Writers have to identify and cultivate your sources, they have to build mutual respect and trust, and they have to follow the story wherever it leads.
Look for writers who can write clear sentences and organize information well, but someone who isn’t afraid to break a rule or two when it serves to engage a modern reader.
They need to be able to adapt their writing to meet your standards and your audience requirements.
Good candidates will have taken the time to understand your company, have a rudimentary familiarity with its products and its market, and be able to show work and tell stories that demonstrate their ability to associate their previous work with the position they are applying for.
Portfolio carry a lot of weight, and it is also important in the interview to have the writer explain how he or she wrote the provided samples.
In today’s documentation world, writers and developers use the same tools and the same project management methods. Let us move beyond the stereotypes and recognize that the boundary between writers and developers is thin and permeable.
we also look for writers who have a true passion for working directly with customers.
you want writers who are: Flexible Fearless Personable Organized Experimental Customer-focused Generalists
we use a set of governing scenarios that span marketing, technical documentation, and customer education to shape a meaningful information journey for customers.
we have found it useful to apply learning objectives as a planning tool for documentation.
A learning objective is an intended intellectual goal or outcome.
Awareness
Comprehension
make a decision
Applicable skill
Design for How People Learn
Writers can benefit from thinking of users as not just readers, but learners. Technical writers do not document a product for the sake of enumerating all of its parts or features; rather, writers craft documentation to support user learning and success.
It is important to consider where you might need to meet users in a given topic.
Staying in both an instructor’s and a learner’s frame of mind can be immensely beneficial for a writer.
Curiosity is one of a technical writer’s most valuable tools or qualities.
Depending on your audience, users might also need information presented in a different order, format, or style from those in which you gathered it.
Another benefit to seeing users as learners is that it boosts your empathy for users and their goals.
Charting a course to a destination on a map or in documentation only works if you establish your starting point clearly (Dirksen, 63). This is essential for both the user and the writer.
A clearly-defined starting point can help users decide quickly whether a topic is going to serve their needs.
helps a user understand how a specific topic fits into a broader documentation set and how to navigate that documentation set.
Present enough context to orient users before they delve into the main content.
Route vs. scenery
Do your word choice, phrasing, and sentence structure serve the learning objective? If not, there is likely a better and clearer approach to consider.
Topics with learning objectives have a well-defined audience and, in turn, support specific user goals.
Generally, it seems best to have one learning objective for a topic.
Avoid general words like “Understand.” Pick a verb, then construct a learning objective, user-story style: “After having read the documentation, I want to be able to paraphrase what stacked charts do and how I can benefit from using them."
a learning objective needs to be action-oriented
Is this something the learner would actually do in the real world? Can I tell when they’ve done it?
Will the user be better equipped to solve a problem, create something, or make a decision after reading this topic?
Can the objective be categorized
Awareness
Comprehension
Applicable skill
user goals are not exactly the same as learning objectives)
creating relevant content is more important than creating comprehensive content.
Advocating for users and asking questions from start to finish helps a writer generate documentation whose objectives are easier to define and support.
names for and within the product can evolve.
more information can surface about a feature as time passes.
Symptoms of documentation atrophy
too long and/or complicated with “patch”
Wordiness or other style issues that make instructions or other information difficult to parse.
Excessive linking to other content, or, conversely, insufficient linking
Heading structures that do not organize the content effectively.
you might find that a single section is no longer sufficient
writers should always consider dependencies between the updated feature and other areas of the product.
Do not neglect the state of your existing material, even though, at the same time, you need to focus on new feature documentation.
Content maintenance should be an important and frequent item on every writer’s to-do list.
Too often, when we think about measurement, we think about precision.
The purpose of measurement is to reduce uncertainty so that you can make a decision based on the results.
measurement has to support a business decision.
Run small, simple experiments. Repeat them often. Refine your approach as you learn more from the measurements you take.
If you’re not going to make a change based on the results, don’t bother trying to measure it.
First figure out what decisions you want to make, then decide which measurements can inform those decisions.
To measure success, you must decide what success means for your organization.
Mark Baker, author of Every Page is Page One, says that mean time to productivity is the only true measurement of whether documentation is successful or not.5
The faster your documentation makes your customers productive, the more successful it is.
Unfortunately, support case deflection is a surprisingly difficult metric to capture, because it involves the measurement of an absence of action.
Define what’s important to your department and the company. Identify a set of business decisions you want to make. Figure out what you can measure to reduce the uncertainty involved in making those decisions.
Run some small, easy experiments, and then adjust your measurements accordingly.
Technical fields have their own language and usage, and to be accurate and understood, we must write for those experts in their language.
To convey a requirement, use “must,” and explain why.
The question to ask when deciding whether to explain implementation is “Why do they need to know?"
Omit implementation details unless there are user-facing consequences. When confronted with oddities, see if the product can address them.
Scenarios provide customers with concrete examples of how they might use your product to solve problems they might have in real-world contexts.
Scenarios help bridge gaps in skill levels, from beginner to intermediate and intermediate to advanced.
Scenarios can bring concepts and procedures to life
A scenario is an end-to-end walkthrough of a real-world example, using the product to solve a problem or achieve a goal that your audience cares about.
A scenario is not a tutorial, which walks the user through a rudimentary example
A tutorial is the “hello world” of learning to code. A scenario is making a photo display on a webpage with HTML.
the scenario is fundamentally interested in solving a problem from a real use case, not introducing a set of product features.
A successful scenario is pitched to a very specific persona.
In the world of technical documentation, editors are content advisors.
Technical editing covers a wide spectrum of writerly things that stretch far beyond catching typos, including: technical accuracy, grammar, style, punctuation, code review, usability, audience definition, and minimalism. Technical editing is all about supporting the writer as they develop content that is going to help the customer be successful.
Writing about writing? Forget it.
Without a shared foundation of style rules, writers will produce documentation with varying styles. Technical editors can help reduce the variation in writing styles by creating a style guide for the documentation team, editing for style when writers submit their content for editing, and encouraging writers to adapt their writing to the style that is best suited to their audience.
Style guides are another channel (besides editors) that can help establish consistency throughout a doc set.
When you’re editing, think about whether the content will be clear and helpful to the user.
How can you learn to write with style? Reverse engineer good documentation.
