Andrew Spittle

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.

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.

Want empathy for your users? Use your own products. Zach Corleissen at #WriteTheDocs pic.twitter.com/8UIOId4Qxb

— MarciaRieferJohnston (@MarciaRJohnston) May 6, 2014

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.

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.

Seeing some interesting parallels between usability solutions @jaredbhatti is using at Google and testing our own products. #writethedocs

— Drew Jaynes (@DrewAPicture) May 6, 2014

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?

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.

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.

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.

"I've never written anything perfect or complete or permanent in my writing about software" #writethedocs

— nina 🇺🇦 (@vyedin@hachyderm.io) (@vyedin) May 6, 2014

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.

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.

“The doc was really readable, but not usable.” #writethedocs Put that on my cube wall.

— Austin Schaefer (@AncientToaster) May 6, 2014

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.

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.

Chernobyl was a documentation failure. #writethedocs

— nina 🇺🇦 (@vyedin@hachyderm.io) (@vyedin) May 6, 2014

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.

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.

Christopher wrapped up the first group of talks before the morning break. His first boss taught him that making sound is not the same as making sense. That concept evolved in his mind to, information is not the same as communication. The standards of music can guide us here.

Since that talk with his first boss Christopher has worked on dozens of types of docs. The metaphor or information and communication has helped him throughout.

The music world defines noise as sound without structure. When you take sound and place it within a satisfying structure you get music. The search for this satisfying structure is innate. When placed in an MRI and given unfamiliar music the intellectual centers of people’s brain light up. They immediately try to make sense of the sound and determine its patterns.

With documentation we tend to accept docs that are failures in the same way as unguided and unstructured noise. But we lack the same fundamental cognitive abilities to identify them. When a document doesn’t communicate it fails. Just like when sound doesn’t exist within a satisfying structure. The likelihood that a document without communication conveys knowledge is extremely low. Ask yourself whether the doc you’re creating contains the necessary information.

Without a theme, and harmony, and a pleasing tempo, you have a document that makes noise. #writethedocs (noise vs. music in documentation)

— Lyzi Diamond (@lyzidiamond) May 6, 2014

Next Christopher talked about deliberate noise. Many times noise is accidental, but sometimes it serves a purpose. The most common lie on the internet is, “I have read and agreed to the terms of service.” No meaningful attempt at communication resembles a terms of service. iTunes, for example, has a 29 page long terms of service.

Music play time equivalent to the time it takes to read the iTunes EULA. #writethedocs pic.twitter.com/vS8ksS9gBV

— Josh Roppo 🌻 (@joshroppo) May 6, 2014

It’s goal is not communication. It’s goal is to protect the legal interests of Apple and to force you to click “I agree” without reading. This is often what noise in documents does; it gets you to acquiesce.

Deliberate noise comes in to play frequently in the legal and government arenas. Documentation noise is treated as unavoidable. But we totally can avoid it! A musical document succeeds by feeding your brain what it craves; it satisfies the innate needs. This music-like satisfaction is more than a nice-to-have, it’s essential.

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.

James isn’t a writer by trade but is rather a system administrator. For him documentation is a way of ensuring that everything works and our users are happy. He works at iFixIt where they teach everyone to repair the products they use every day. The documentation on iFixIt’s site is all wiki-based and very graphics-heavy. About half the guides are user-contributed.

As James said, good documentation’s worst enemy is bad documentation. Not everyone loves writing documentation and when the love isn’t there the quality can suffer. There’s something different in our brains about docs. We don’t treat them like software and, as a culture, are sometimes numb to documentation. We assume it’s bad and avoid reading it. If we can focus on increasing the quality of docs we can combat this numbing effect.

When you allow bad documentation to linger it drags the quality of the overall library down. A similar effect to the broken windows theory. Bad documentations allows for people to internalize the notion that it’s okay to have crappy documentation. That’s not what we want; we want high standards for quality. As an aside, outdated docs fall in to this bucket as well. Updating them is frequently an easy thing to fix.

The first category that James really, really hates are auto-generated docs. There are three great virtues of a programmer: laziness, impatience, and hubris. Laziness is what drives us to create auto-generated docs. Frequently the result is not worthwhile, not in-depth, and not reviewed with an eye toward user-facing clarity. Javadoc may be a good tool but it’s gone bad. Just because you can do something with a tool doesn’t mean you should. Computers, at their core, suck at writing docs for humans to read.

James then covered the second category of bad docs, those that use overly verbose language. By knowing your audience you can find places to omit needless words. One audience may require great detail while another can do with just an overview. ssh allows for 4 levels of verbosity within the tool itself. What James seeks is a documentation equivalent of that.

The final thing James talked about was mistake-proofing. Humans will always make mistakes, but mistakes don’t always need to become defects in the final product. An engineer at Toyota came up with the concept of deliberately designing mistakes in to your product creation process. The trick is to fix these product failures rather than documenting around them.

After the talk James posted his slides. Check them out.