Tag: Write the Docs

Session notes from Write the Docs, a conference in Portland, OR and Budapest, Hungary about crafting great documentation.

Documenting Conferences

Last week I attended Write the Docs. As with previous events I took real-time notes of the talks. Over the last two years that resulted in 32,515 words of notes. It seems fitting to spend so much time documenting a documentation conference.

The ephemerality of conferences frustrates me. Events bring a knowledgeable group of people together. During the conference energy and ideas are palpable but when attendees go home that all fades in to the ether. The occasional slide deck makes it online, but we lose so much. The context, references, and verbiage of a speaker are lost. Scrawled notes on paper are rarely, if ever, shared with those who couldn’t make the conference.

Freely available, web-based, text notes persist across time. Those not able to attend can still learn. Those who do attend can reflect and remember. Ultimately, when the conference ends the learning continues. When multiple people publish notes you learn what parts of a talk resonate with whom. You are able to collectively document a shared experience.

In the future I would love to see more people actively documenting conferences. Notes help us move our respective communities forward. With notes speakers can build upon the talks of others rather than reinventing the wheel with each event. Notes help us spread knowledge beyond the few hundred people fortunate enough to attend. With notes we assert control over the ephemerality of conference knowledge.

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.

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.

Write the Docs: Lauren Rother – We Strongly Recommend You Write Best Practices

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.

Lauren is a tech writer at Puppet Labs. She focuses on the Forge, a repository of community modules for Puppet. At Puppet the docs team falls under engineering, and the writers are embedded within the various development teams.

The challenge they face is that users have different needs, environments, workflows, and most importantly, levels of experience. The experiment Puppet tried was the beginner’s guide to modules. They’re in the process of writing an advanced guide, which would incorporate what they learned from the beginner’s guide.

In the first draft they took inspiration from textbooks. They brain-dumped everything in to a Google Doc which they then sorted in to 4 sections. They wanted to present heaps of information so that everyone who needs a foundational knowledge of modules would be satisfied. It was immediately apparent that the document was overwhelming. It was hard to approach and the first section in the document was disproportionately huge.

What they realized was that the first thing they needed to do was create sign posts within each section along with sub-sections. The took a more orientation-based approach to writing the document. This second take at the document produced something much more readable and comprehensible. Large paragraphs were broken up and edits were geared toward orienting the user. It was still really difficult to navigate and locate distinct items, though. You constantly were going back and searching for where you left off; it wasn’t easy. In short, the doc at this point was really readable but not usable.

They realized they’d been working on a treatise, not a guidebook. They dropped the academic standpoint and textbook approach. What they really wanted was a doc that people would want to look at more than once, not something they’d only read because of its challenging nature.

In hindsight it seems really obvious that a step-by-step approach was necessary. It didn’t occur to them to take this approach, though, until they were 2 drafts in. The final version has a table of contents, headings, steps, introductory sentences and examples. All around it was a huge improvement.

Lauren couldn’t help from thinking about future improvements, though. There wasn’t enough get-your-hands-dirty details in the beginner’s guide. It was too high-level at times. She’s taking some of these lessons and applying them to the advanced guide to modules.

Write the Docs: Brian L. Troutwine – Instrumentation as Living Documentation: Teaching Humans About Complex Systems

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.

Brian kicked off the slate of talks after the morning break. He’s a software engineer who focuses on computer-to-computer programming. It’s not as much end-user software. He primarily works on real-time and distributed systems. A lot of this is for advertising companies and takes the form of real-time bidding on ads.

Advertising has become an engineering-driven industry. It’s lowered the cost of advertising and allowed people to spend as little as $10 a month for their business advertising. The nature of the problem in this world is it super low latency (less than 100ms per transaction) and global, highly concurrent nature. The complex systems to execute this have complex organizations around them. They’re tightly coupled to external systems and have non-linear feedback built-in to them.

Bad things happen when these complex systems fail. You’ve built them to solve wicked problems and when they fail they sometimes create even worse problems then they originally solved. Ultimately, “our ability to create large and complex systems fools us into believing that we’re also entitled to understand them.” To work toward that understanding we write documentation.

The issue is that complex systems are fiendishly difficult to communicate about. The gap of understanding is difficult to bridge in documentation. Any miscommunications around complex systems are accidents in the making. Documentation can help to reduce these accidents. It can help give everyone a greater shared understanding of the system. Without knowing how a system should behave you cannot really understand how it shouldn’t behave.

An issue with understanding through documentation is that the docs get out of date. Complex systems evolve and written words “rot” as the system moves on. Sometimes this falls on engineers for failing to update what they change. Or, engineers can be unaware of the system as it is actually used. This contributes to misunderstanding through docs.

Normal accidents happen as well. Every system has, intrinsic to itself, some failure. No matter how much we try we can never get rid of them, we can only choose how to react in the presence of such an accident.

How can we build better systems that distribute knowledge and better avoid accidents in real-time? Brian’s argument is for instrumentation. This reflects the reality of the system as it exists. Instrumentation allows the users and the engineers to explore the system as it actually exists. This exploration, done honestly, guides us to a new, better understanding of the system. Instrumentation also democratizes the organization around a complex system.

Troubleshooting complex systems can sometimes be limited by not having enough information. If you’re relying upon external services there’s a level of opaqueness that you cannot see through. But, instrumentation is not a panacea. It can also create an overload of information that floods your ability to make sense of the system. Too much information hampers interpretation.

On a darker note instrumentation can be used for undesirable purposes. Surveillance is a form of this. Complex organizations with excessive instrumentation can do evil things.

What we should do is write documentation with the instrumentation in mind. Procedure manuals and visualizations, for example, reduce the amount of complex knowledge required. The more contextual layers you add, the more you reduce the “big boards with blinky lights” issue. Instrumentation is like a suit. It needs to fit your mind. Cross-checks and documented error margins mitigate instrument deficiency. Checklists with references to instrumentation at decision points is key. It pinpoints where attention should flow and how to process it toward informed decisions.

So, instrumentation addresses the problems of documentation and documentation addresses the problems of instrumentation. Together they help guide and ensure the quality and understanding of complex systems.