Tag: documentation

Worthwhile Documentation

Detailed support docs are not enough. If they were, our queues would be emptier. A good doc builds a customer’s confidence and helps them find clear, approachable answers. They won’t find that, though, if we don’t make documentation seem worthwhile.

Any customer who contacts support is motivated to solve their problem, but that doesn’t mean a simple link will be enough to draw their attention. A support doc still has to sound compelling. And yet too often our replies tack on a link to documentation as an afterthought.

To make a doc sound worthwhile, focus on the words right before a link. I know I’ve sent many a reply like, “You can read more about this here…” with a link. That sounds superficial and ignores important context and direction. My job is to give the customer a look at what’s inside the doc and how it can help them—but a minimal reply like that does neither.

It helps to think about what the doc contains that I couldn’t just copy and paste into an email response. Here’s an example that makes it sound more worthwhile:

There’s a lot more you can do with this feature and our support doc covers all the details. That link takes you through everything and includes screenshots to help you find each step and get it set up exactly how you want.

That reply is longer, but it puts more energy behind the link. The customer gets a thorough nudge and greater confidence this is information they need to know. They can see documentation as more than just a dry manual and have a hint that it will help them be more effective. Manuals are off-putting while a good support doc helps someone learn and build confidence.

It’s extra special if you can include tidbits into some docs. If a feature’s key to the product, document a couple (brief) case studies or next-level steps. With those included you can add something like,

And check out the bottom of the page for tips from some of our largest customers about how they use this feature. There’s good advice in there that can help you avoid common mistakes.

This takes a support doc from simple help material to something more like educational marketing. It shows a customer not just how to configure a feature but how to thrive. That may save you another email from the customer later on once they’ve mastered the basics.

There’s, of course, much more that can be done with documentation. To overhaul a set of support docs can be a mountain of work that takes weeks or months while improving our own replies is work we can start today. There’s no development time required nor any software to integrate. It’s something each team member can tinker with and learn. Customers are willing to spend more time with docs once they know it’ll be worth their while.

Documentation, Support, and Customer Success. Simon writes about how documentation is a psychological band-aid in how it calcifies habits and shifts responsibility.

People will read

Last July Ryan Pitts and Sara Schnadt led a session at SRCCON about human-driven design. It wrapped up with a discussion of various maxims that guide design processes. Someone in the room said it was important to remember that, “users won’t read, ever.” That rubbed me the wrong way at the time and I went on a mini-rant in the session. I was thinking back to this recently and wanted to sketch the idea out into a longer post.

The perception that people don’t, and won’t, read documentation is not uncommon. There’s a reason we have the acronym RTFM after all. I think it’s a perception that’s horribly misguided and short-sighted for your product.

People will read. What they won’t do is unquestioningly read on your terms.

Treat docs as product

When you’re developing a product you don’t ship something and passively wait around for it to become popular. If what you shipped isn’t gaining traction you iterate. You tweak and adjust until your product fits its addressable market.

For some reason we don’t approach documentation with the same mindset. Our predominant expectation is that we can ship docs and expect every person to read them. If the docs have up-to-date screenshots, are detailed, and are searchable then that’s enough. If people don’t read, that’s their fault not yours. That’s a fundamentally broken expectation.

Most importantly, if you react to support requests by wondering why people can’t read the docs then you are missing a golden opportunity. You are directly blaming the person using your product instead of blaming your product for requiring documentation in the first place.

Exploratory & Prompt-Driven Users

Part of the RTFM-mindset stems from an assumption that everyone is an exploratory learner. That’s wrong. It’s arguably true for many tech folks. That doesn’t make it true for many people using our products.

Exploratory people will find their own way. They are comfortable with uncertainty. They’ll use a confusing product and feel confident relying upon documentation for answers. To them this is part of the appeal. Each awkward setting or obtuse workflow is an opportunity to master the intricacies of yet another product.

Prompt-driven people will read docs, but it’s not their default. They will first look to your support team for help. You could also think of them as human-reliant people. Interactions with your support team may prompt them to read and reference docs. So it’s not that they won’t read. It’s more that they prefer human interactions to help guide them.

Here’s the thing about prompt-driven people: they are a potential gold mine of qualitative feedback. There is no better source of information to help guide your product teams. Yes, this means your support team has more tickets to respond to in the short-term. That’s a great thing.

Every one of those interactions is an opportunity to learn more about how people use your product. If you choose not to take advantage of that and instead blame people for not reading your docs and leaving you alone in your cave, then that’s your loss. The next time you find yourself blaming a customer for overlooking the “obvious” answer in your docs, ask yourself whether you’re reading enough of what they’re telling you. More often than not I think it’s those building a product that don’t read, not our customers.

Thanks to Simon for helping clarify some of the wording in this post.

Write the Docs: Mark Tattersall – Documentation as a Product

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Mark wrapped up the conference talking about documentation as a product. Mark is a product manager at Braintree. There the API is, in a sense, their product. When he started there they had no getting started guides, no tutorials. That was the first thing he worked on and the first things he shipped.

We tend not to talk about documentation as a product in itself. We overlook it and lump it together with the product that it’s documenting and representing. It’s frequently relegated to a line item on a project plan; “We need to write the docs so that we can get this shipped.”

Docs thinking is somewhat tactical. You work through the tone and voice of your content, who the audience for it is, and the format it will take. Mark wanted to take a step back from the tactical, though, and look at documentation more holistically. We need to understand docs as something intimately connected and integrated to the product. You think about the problem first before jumping in to the ins and outs of creating a solution.

Product thinking is a lot about burning through a series of questions to get at what applies to your particular need. Those questions include:

What problems are the docs solving?

The fundamental question for any product. If you can’t understand the specific problem you must question what you’re doing in the first place. Your documentation has to cater to both existing and potential users.

Documentation is, in many ways, the analog to turning over a physical software box and reviewing the details of a product. Documentation can be the first enduring interaction that users have with your product. It acts as a reference and an index all in one.

Who will be using your documentation?

You can get at this by creating personas of your users. You don’t have to do this but it can be a great exercise; it’s something that they do a lot at Braintree. To do a good job of this you need to get out there and talk to your users. Talk to other groups within your company, too: support, accounting, marketing. Anyone who talks with your users is worth talking to.

When thinking about your users keep in mind that you don’t have a linear relationship with them. You don’t get to hand-hold them from A to B. They will choose their own path through your docs and dip in and out of the content. Users may even find their way there from any number of sources.

How should your documentation communicate with your users?

This is not a docs-only decision. You need to put it in the context of the company and the product set. Consider how your company talks with customers and what the product emphasizes. Find the voice and persona of your own product and make that shine through in your documentation.

https://twitter.com/foxesinsockses/status/463828288192794625

What is the vision for the product you are documenting?

Where do docs fit in the grand scheme of things? You need to understand where the product and company are going. You want to make sure that your docs can handle the changes that are coming down the product pipeline. By establishing the core message of what you’re documenting you make it easier for users to orient themselves around that.

What does success look like?

Are your users achieving their goals when they are using your docs? They need to be getting answers to their questions and solutions to what they need. If you can, do a survey. Find data and information about the baseline for customers interactions with your docs. That lets you see what direction your efforts are moving the docs.

You can also look at funnels, analytics, calls to action, and engagement. Talk to marketing and other groups in the company. There are likely shared things you can incorporate in to your docs approach.

What do your competitors docs look like?

Learn from those around you and from different fields. Get plugged in to where people are talking about documentation and learn how to make yours better. After that research do different and do better. Don’t just mimic and mirror behaviors elsewhere; iterate on them and make them your own.

Execution

So, with those questions in place you can dive in to building your docs. Before diving in consider your information architecture. Consider your content, context, and the users you’re solving for. Let your answers guide your architecture; otherwise your content is at an immediate disadvantage.

Write the Docs: Patrick Arlt – Ditch your CMS with Git and Static Site Generators

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Patrick started the afternoon talks after the amazing snack break. He posted his slides ahead of his talk, smart idea. Patrick works at Esri and previously worked at Geoloqi. There he fell in love with making products for developers. When Geoloqi was acquired by Esri he started working on the ArcGIS site for developers.

This site aims to do something great for Esri’s developer community. They try to reach new markets and promote the broader platform. The first version of the site was a single, simple page. It took a few weeks to get up to 6 or 7 pages. Over time they added more and more information to help bring people on board.

Eventually they realized there wasn’t really documentation on the site. It was a lot of external links and pointers. What they had was thousands of pages of doc for dozens of projects with all of it sitting in an old CMS that no one liked. Entire teams had built their own CMS just so they didn’t have to use the painful CMS. This wasn’t what they wanted.

What they wanted was a way to develop documentation like they develop their own product. They wanted to shift to not just writing documentation but building documentation. That led them to look at their existing toolkit and see what could be applied to documentation.

The first thing they had was a static site generator. This let them treat documents like source code. There are tools to build large amounts of pages quickly. It’s like a CMS but all the files sit on your local computer. Needless to say there are tons of choices. Static sites take care of the hard parts of building a website so writers can focus on writing content.

Within this site generator they use Markdown for content. It’s a very simple language that, under the hood, gives them a lot of advantages for writing documentation.

The last tool they really rely upon is the git / GitHub combination. They use it to manage all of their source code so it was a natural extension to use it for documentation content. The GitHub portion is used for tracking issues. They use the issues feature in GitHub to track bugs in documentation just as you would with a code project.

These tools mean that teams have a lot more ownership over their documentation. Anyone who is a part of the organization can contribute to documentation using the same tools they contribute to the product with.

To those concerns about the learning curve with all these Patrick suggests placing it in the context of bring new people up to speed with a complicated CMS system. In each case you’re needing to train people and maintain internal documentation on best practices.

But what about all that documentation in their old CMS? Well, they’re still using it. Patrick sees that as an okay combination. They’re able to serve the static files alongside the old CMS content.

Esri is next looking at 3 main things:

  • More automation. Things like making previewing site changes more easily.
  • More custom tools.
  • More training.

Write the Docs: Zach Corleissen – More Than a Reference: Better APIs through Empathy

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Zach is a technical writer at Moz where he focuses on API docs. He kicked things off with some Q&A to help guide where he’d take the talk.

For Zach, empathy is the ability to mutually experience the thoughts, emotions, and direct experience of others. It’s not exactly sympathy, though the words are often used interchangeably. It’s possible to be sympathetic without being empathetic. To write empathetic API docs, you have to understand and share your users needs. The easiest way to do this is to be an API user yourself. Dogfood your own product.

To gain empathy, gain experience. There’s no shortcut around it; you have to use your own API. Using other APIs will help you identify the strengths and weaknesses of your own API.

To write with empathy you first have to know who your readers and your API users are. To learn this at Moz they ran a customer survey; but they ended up with data that wasn’t a large enough sample size to be statistically valid. While not statistically valid it was useful. Once you’ve learned who your readers are, write for them. Write to that audience, their background, and their skills. Frequently you’re writing for other reasons than your readers. Deadlines come in to play. Business incentives force their way in.

They found their readers wanted sample code and written documentation, in that order. Ultimately code samples are written documentation as well.

The best thing you can do in your documentation is to tell true stories. If someone’s in your docs you don’t need to market to them; just establish trustworthiness. To help guide this, ask why does this API matter? True, trustworthy stories help convey that information.

Your API docs also have to provide a friendly UI. It needs to be approachable for your target readers. One approach to doing this is to use single-page docs with stronger typography.

You also must lavishly document failure states and edge cases. You can technically push this off to your support team but documenting it will save you so many headaches.

Empathetic API docs challenge you to deepen your technical skills and care for the needs of others. Deeply technical material requires you to be empathetic. Empathetic API docs delight your readers exceptionally. It turns moments they wouldn’t expect in to pleasant learning experiences.

Write the Docs: Jared Bhatti – The Getting Stopped Experience: Improving Your Content’s First Impression

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Jared works at Google and attended last year’s conference as well. Coincidentally he was starting a new project at Google working with their cloud products. Google’s cloud platform encompasses everything from computing to storage to app services. Each segment has its own getting started experience. But each segment can also be combined with others for another, unique getting started experience.

He started with a hands-on exercise to get everyone thinking about what challenges they face in getting users started with a product. At Google they found users had a hard time finding information and the results that did come up were complex and dense. On top of that there were poor connections between the team and the user communities. They were expecting users to come to them with helpful information.

They looked at getting started as a 3-part journey. Someone has an idea and then goes through 1) finding helpful content 2) getting something working 3) getting the envisioned project working.

The first step, finding helpful content, is unfortunately where lots of people get stuck. With Google Cloud Storage users were getting irrelevant Google search results, each of which took multiple clicks to find the details for. They compared this to Amazon Web Service results which were highlight relevant and generally one-click away from the getting started experience. To fix this they did a few things. They started running searches on their own products. They worked to understand how users were actually finding their content. And, they looked at what competitors were doing far better than they were. With competitors they looked at large and small; frequently it was the small competitors who were doing really interesting stuff.

In terms of getting something done once you’ve started Jared focused on Google App Engine. The first thing Jared did when joining the team was try to spin up an app. 24 steps later he was done. 24. Way too many steps for a first-time user. There were so many dead ends you could run in to before you even started. Luckily everyone on the team recognized this as a large problem. They launched 21 projects around this in just a few months.

As they collected data they looked what tools and resources were being most utilized and useful during a getting started process. They focused on pain points that new developers face. Through questionnaires, researcher observations, presentations, and informal conversations they gathered data. They adopted user-first principles as well:

  1. The user is always in control.
  2. Give the user what they want quickly.
  3. Reduce friction. Everywhere.
  4. Show, don’t tell.

The trick is to give users consistent value from your application and product. They brought the ‘Hello World’ experience down to 4 key steps. It dropped down to just 15 minutes of work for the interested user. When Jared first went through the steps that same process took 4 hours. They then took that a step further and brought a widget in to the technical documentation that lets users generate a ‘Hello World’ widget in just 30 seconds.

Lastly, in the third act of getting their product working, users look to launch a complex application. Essentially shipping what their original idea was. For this they focused on community outreach and happiness surveys of customers. It was about bringing external feedback in to the product development process. They also started a GitHub repository with fully fleshed out applications that people can download, tear apart, and launch themselves.

Jared left us with a few questions to consider for our own products:

  • How are your users getting to your docs?
  • How long does it take to get to ‘Hello World’?
  • What metrics are you collecting?
  • How are you interacting with your larger community?

Write the Docs: L.S. Cook – Scale for support without losing personality

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Leona kicked talks off after lunch. She views support, documentation, and in-product design as all fundamentally connected. She asked, as writers, how we can not shut out those who learn best through non-written formats. People who are non-technical by trade are learning software through the products and documentation we create.

One hat for helping users is not better than the other. From engineering on up the stack, it’s all about helping users on some level. The public-facing content you have, though, is what gives users a personality to equate with your brand.

With in-product design there’s a lot to consider. You need to think about what device someone is using, the visual order of the design, and the overall flow. For docs particularly, the whitespace and visual order can greatly impact how someone reads and scans the information you present. Principles of good design can apply to other spheres as well.

Leona argued that support is the only that deserves the title of “ninja.” They’re the strongest link to triage and approach any 1:1 interaction with a customer as an opportunity for learning.

Documentation and tutorials are not synonyms. Tutorials are a unique type of content, and something that’s not used enough in the world of docs, we should change that. These tutorials are one opportunity for companies to make money. They can hook your users in to your product and really illustrate how the product will solve their problems.

Write the Docs: Britta Gustafson – Strategies to fight documentation inertia

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Britta wrapped up the talks before lunch by talking about documentation inertia. The talk was about what she learned through reviving the community wiki she works on.

For a few years the wiki had an outdated tagline and a list of ideas on what to add but no mention of the existing content. Now, though, the main page has a statement of goals, lists of interesting articles, information on how to get started, and links to get help with editing. 60 great volunteers helped contribute to this renovation.

Britta works for the 3-person company that makes Cydia. The wiki in question is the documentation for using this jailbroken OS. The wiki content is all done on a volunteer-basis to further the community. How do you get started writing about these crazy jailbroken customizations, though?

That’s where documentation comes in. For a long time, though, Cydia had very little documentation. People had to just figure it out as they went along. Britta was contributing to OpenHatch, though. It’s a project for learning how to contribute to open source projects. Through this she got experience helping developers with development problems, even though she herself is not a developer.

That gave her the confidence to start working more closely with the developers in her own community at Cydia. She threw a few strategies out there to help with this.

  • Show up and be someone who cares. If you hang out where the developers are that’s the first step.
  • Talk to newcomers and beginners. Find where the pain points are and write them down.
  • Ask encouraging questions to counter anti-documentation concerns. Write down advice for those who don’t read the docs.
  • Think of documentation as a marketing problem. Make the homepage enticing to click and put the best stuff right up front.
  • Make writing more fun. Show that there are people reading it. This can even be immediately copy-editing new writing as it’s contributed.
  • Make the wiki fun by making it look active. No one wants to contribute to a silent project.
  • Understand that the docs system needs docs. Not every editing tool is understandable to the unfamiliar.
  • Leave some rough edges for others to smooth out. Easy tasks hook other contributors.

Write the Docs: Scot Marvin – Wabi-Sabi Writing

I’m at Write the Docs today in Portland and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Scot covered how we can use wabi-sabi in our writing. He first started reading about wabi-sabi when his first child was born. He found the first rule of wabi-sabi seemed to be that you don’t talk about wabi-sabi. It has a respect for syntactic ambiguity which goes against much of our Western ideals. Essentially, though, it’s beauty in impermanence, imperfection, and incompleteness.

Our Hellenic ideals push us toward perfection, but ultimately we create very little of perfection. Wabi-sabi embraces the rustic and the simple. It allows for tranquility but also asymmetry. It’s not about being a Luddite. It’s also not complacency. Allowing for imperfection does not mean accepting the generic. You strive for excellence, not perfection.

Scot works in an agile software environment. Essentially agile means finding out where you are, taking small steps toward your goal, and then adjusting your understanding based on what learned. It, like wabi-sabi, is not about creating perfection. It’s a repeatable process that lets you improve and strive toward excellence.

He tries to abide by four suggestions in his writing.

  1. Less Faulkner, more Hemingway. They are the two extremes of America writing. Write in simple, clear sentences. Your documentation should be clear and concise.
  2. Less Coltrane, more Davis. Or, strive for tranquil writing. Miles Davis was known for his economical restraint when it comes to music. Scot strives to put support out of business with his restrained documentation.
  3. Less Versailles, more Ryōan-ji. Work toward simple writing. Your docs shouldn’t be the equivalent of the gardens at Versailles. This can also be thought of as the, “Don’t get too cute” principle.
  4. Done is beautiful. We can’t truly complete anything, but we can get it done. Incomplete, imperfect writing is okay. Incrementally make it better; don’t just wait for perfect completion.