Andrew Spittle

I’m at Write the Docs today in Budapest 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.

Jessica comes from a humanities background and about a year ago started teaching herself to program. She works for Majestic SEO and, when they found she was learning to program, immediately set her to work on the product’s documentation.

When she started out she wasn’t really sure what she was doing. Tone is about feelings and Jessica didn’t really know how to add that in to documentation. She found that you can’t seek out concrete rules for tone, it’s more of an art than a science. The most important thing to remember, though, is to use tone as a reinforcement of your brand’s voice; just don’t make it too sleazy.

Tone shows your users who you are. It broadcasts what you wish users feel about you. It can also communicate who your intended audience is and what your expectations are for how they will, or might, interact with your product. Finally, it indicates the level of interactivity you’re willing to maintain with your clients or users.

Part of talking effectively to your audience is accurately assuming who your readers are. Setting those expectations from the outset involves looking at skill level, whether they’re an individual or organization, commercial or non-commercial. It’s so easy to get this part wrong. Misjudging your audience can limit that audience through a tone that’s at the wrong level. You can also exclude potential users through the use of culturally limited references. Overall setting expectations is about asking what tone you want users to carry through your product.

Tone is also about the level of creativity your users must take. For example, are you inviting them to try and break something? Or, are they needing to conform to a level of professionalism or specific niche.

We can also use tone to open up the vision or aspirations for our users. Tone can encourage users to set a broad, but not too broad, scope with vast creative potential. What gets messy is setting multiple levels of user expectations.

Before you set the tone for interaction you can run through a set of helpful questions. What kind of resources are you making available for user support? Are you building a community? What level of transparency are you aiming for? All of those things can help set the proper tone.

Jessica highlighted Buffer’s API documentation as a great example of tone. They set a very personal tone that helps direct users where to contact them. It’s lots of “you” and “we” throughout.

There are times, though, when you need to divorce from your voice. When your audience for documentation and the main product diverge. Or, when the branded tone suggests a level of support or interactivity you’re unable to support. You can also dilute your voice a bit in documentation. It doesn’t have to be an either/or situation.

Ultimately, when you’re writing you have to ask who your users are, what you expect them to be doing, and how much interaction you want to promise them.

I’m at Write the Docs today in Budapest 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.

Thomas started the sessions after lunch. He’s a JavaScript Engineer at the BBC. In 2011, after returning from a trip to Iceland, Thomas attended a conference in Paris where someone covered research illustrating how people learn more effectively from talking about something than reading about it. It prompted him to think about whether we should be talking about things more than relying upon static documentation.

He was working at a startup that grew from 1 to 5 and more projects. They needed a better way to document what they were doing. As he put it, so much time is put in to writing code that powers useful software. We want to share our work and findings. Documentation, in part, becomes how that end result is communicated to others.

At the startup they moved toward README-driven development for a few reasons. It’s the default file that GitHub displays, for one. A README is a simple and fast piece of content to write. It can also be written and then transformed in to any number of formats. The goal is to sum up what software does in a few sentences.

At any point you can use any number of tools to edit a README alongside the versioned code. You’re not pushing people to a separate website to learn about the software. Through the inclusion of examples and effective content you can help people right within your source files.

With intro information contained in a README you can tell at a glance the limits of your software. Setting shallow limits for your README helps ensure users can understand your software quickly.

Part of what’s key about README driven development is that it’s about ideas and new projects just as much as it is about existing work. You can lay the groundwork in your README before you write any code. It can create crystal clear guidelines for developers and allow you to gather feedback before shipping your code. By writing the README you are sketching your idea of what will be produced. Doing all that work ahead of time allows you to iterate faster.

This all helps in detecting complexity. As your README becomes more complicated it means you’re maybe trying to do too much within one project. It can be a helpful marker to when you need to break things in to their respective pieces.

Focusing on the README can even help in pull requests, bug repots, and other aspects of development. Being detailed there focuses on the intention of your code rather than the code in isolation. That can prompt discussion about whether the intention is ideal regardless of the code attached.

Ultimately focusing on the README first gives users a single entry point to your project. It emphasizes the correct things, makes dialogue easier, and gets you to top-quality code faster.

I’m at Write the Docs today in Budapest 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.

Markus is an independent software developer and software trainer. Sphinx is a python-based tool for generating documentation. It will output in to a variety of formats including HTML, ePub, and plain text. His talk focused on the internationalization of text written in Sphinx.

Internationalization is the translation of text in to other languages without changing the underlying code. It leaves the markup and HTML structure of the text unchanged.

How internationalization works in Sphinx.

Sphinx has an introductory page about how internationalization works. It walks through examples of using gettext as well as the general process.

sphinx-intl is an extension that makes the translation process much easier. It lessens the command-line nature of the task and generates binary files for your translations.

Transifex is a commercial solution for speeding up your translation process. It’s a modern webapp that makes collaborating on translations easier. They also have a free option for open source projects.

I’m at Write the Docs today in Budapest 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.

Idan is a designer/developer at Heroku. He’s also a core designer for django. He started his talk clarifying the difference between typography and typefaces. Typefaces are just a subset of the broader typography field, which is the art and science of presenting textual information.

There’s micro (typeface, kerning) and macro (measure, leading, flow of type on a page) typography.

We’ve been designing books for centuries and there are all these built-in guidelines for typography in printed form. It’s all about control there. Since printed content is static the designer can control the consumption experience.

The web, though, presents us with a anarchic lack of control. We don’t even know where or with what screen someone is reading our words. And, many times, in the most constrained setting is when the reader needs your text the most. As documentarians this is where you have to deliver, this is why you have to care about typography and the web.

Typography on the web is still in its infancy compared to printed type. Sometimes the new, cutting-edge tools are hard to use. But they do pay dividends when used properly.

Type size is one of the primary levers you have for controlling text displays. Browser’s set the default font size to 16px. Books, though, set a default of around 12px. The difference here is that we hold books much closer when reading. If your content is going to end up on a screen the larger size improves its legibility. When setting type size proportional sizing, ems or percentages, is ideal. An em is a box that is roughly the size of an uppercase M; that’s the largest character a given font will need to display. An em is a unit of measurement that is proportional to the typeface used. This lets you change your typeface later on and not ruin the proportions of your design.

CSS3 introduces the rem unit, which is a root em and makes sizing easy. Everything goes back to the root so you’re not tracking relative sizes down the HTML stack.

Browsers apply font families character-by-character. Fall back families are used when the primary choice doesn’t include a given character. Idan also dove in to how font-face interacts with a browser’s display of text.

The dreaded FOUT can also affect our docs. Readers will see the default font applied just before a custom font resource loads. When the new font resource does kick in it also affects the layout of our page. This is because the browser adjusts the font metrics used. Adobe Blank is a tool that can help with this. It’s a font that purports to contain all characters. This ensures no text displays until your custom font arrives. Additionally there’s a spec in progress that will allow you to hook in to font loading actions.

Your journey toward really good type doesn’t end there, though. You can dive further down the rabbit hole in to type rendering. Rasterizes turn outlines in to pixels. They transform our fonts from smooth vectors to on and off pixels. Windows, for example, uses three different rasterizes. There’s even a handy guide to figuring out which will be used under what conditions. Mac OS X, though, uses just one.

The bottom line, though, is to test your typeface. You can’t rely upon just one operating system or just one browser. Everything can impact how your text displays.

Idan also published his slides on Speaker Deck. You should check them out for more details (and for the beautiful design).

I’m at Write the Docs today in Budapest 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.

Shwetank is a web evangelist at Opera. He’s worked there for 6 years or so now and is the main author of the Opera Extensions Docs.

A year ago Opera moved their platform to Chromium. Their extensions platform switched to accomodate chrome.* APIs. They had to either re-document everything from the ground up or take Google’s existing docs and improve them. Both were difficult options. On the one hand it would be hard to re-create something. On the other it’d be difficult to improve upon an already great product: Google’s Docs. Ultimately they took a look at Google’s Docs to see what they could improve.

What needed to be communicated in these docs was Opera’s architecture, extension APIs, and AddOns Store. The aim was to be easy to understand and to explain the most common use cases.

As an extensions developer himself Shwetank could empathize with what the users of this documentation would need. He ran in to many hurdles in trying to understand the platform and documentaed the solutions he found.

They set the scope of improvement upon Google’s Docs to be:

• Unified architecture explanation
• Easy to follow tutorials
• Explaining common use cases
• Simple sample extensions

The architecture needed to be explained on one page. The tutorials for essential APIs and functions needed to be accessible to new developers. Docs needed to cover a breadth of common uses, such as closing and opening tabs.

The core of this improvement process relied on making sample extensions for common use cases. By documenting the issues Shwetank came across he was then able to write an article which improved upon Google’s core docs.

On the technical side of things they built the site in Jekyll while using Markdown for the tutorials and an API Docs in plain HTML. It’s available on GitHub.

Sample code must be as simple as possible with as few lines as possible. It’s a starting point to build from, not an exhaustive source of implementation. 20 pieces of sample code that each do one thing is better than one monolithic code example that does 20 things.

One thing that worked well for Opera after publishing the new docs was using multiple channels for feedback. They heard from people on Twitter, email, and Stack Overflow. Much of the feedback was about abstract scenarios.

Still to come in the docs is an improved navigation, boilerplate extension generator, translations, and adjusting the tone.

I’m at Write the Docs today in Budapest 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.

Kelly runs O’Brien Editorial, a technical writing business that works on documentation for small Drupal shops and large enterprises. She started as a journalism major in college and wrote about everything from food culture to trends in eco-construction materials. Through that experience she learned about how to target writing to your audience. In other words, how to engage your readers.

Engagement is about holding your readers’ attention but also means earning the trust of your readers. With documentation you want readers to rely upon your documentation for help. That starts with trust.

Readers must trust that you understand where they’re coming from. That you sympathize with their frustrations. That you know what they need to accomplish. That you’ll help them solve their problems.

If you don’t do those 4 things readers will ignore your docs. Kelly calls this Doc Death. There are 4 kinds.

The first is Death by Apathy. Think of readers as teenagers; if they detect that they have ceased to be the center of your universe they will tune you out. To fight this you need to put your readers first. Prevent apathy with empathy. The first step is to recognize that the things that are most important to your readers are not necessarily the same as the things that are most important to you. To learn what’s important you can ask what they care about, what they struggle with, and what they need from you.

Death by Alienation is the second form of Doc Death. Readers are a sensitive bunch. If they ever feel that you’re not on their site they will put your docs down and not touch them again. Your voice is one of your most powerful tools to combat this. Use it wisely. Tiny adjustments can make a huge difference to your readers. In your docs tone of voice is about formality. It’s a spectrum between academic and relaxed. The goal is to find a place somewhere in the middle. To do that you should take 3 things in to account: the company culture, the purpose of your docs, and the tech savviness of your readers. Whatever tone of voice you choose, be deliberate about it and employ it consistently.

The third type of Doc Death is Death by Impatience. The last thing your readers want to do is to hunt for answers. If it takes your readers too long to find what they need, your docs will be ignored. Organizing your content helps fight this. You should lead with the problem that the document solves. It makes it clear to your readers what they’ll learn by reading. It helps if you ask, “If it read this, what’s in it for me?” The secret to reader engagement is WIIFM: What’s In It For Me. You can make this clear to your readers by simply telling them. This should happen later in the writing process. The first step is to get everything on the page; then you can go back and make the WIIFM clear.

The last form of Doc Death is Death by Disorientation. Readers have relatively short memories. If your reader every wonders “Why are we talking about this?” your docs are in trouble. The solution is to use powerful pointers. Using pointer sentences helps your readers orient themselves. Pointer sentences recap, state, or foreshadow the information you’re presenting. They create a contextual structure for what readers are looking at. They also allow you to show that your readers’ needs come first. They remind your readers that they’re not alone. Finally, they communicate the WIIFM to your readers.