Tag Archives: conference

The Internet With A Human Face. The transcript and slides from Maciej Cegłowski’s fantastic talk at Beyond Tellerrand. It winds through the alienation and mass data collection of the internet but ends with a forward-looking vision.

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.

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.


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.