Tag: conferences

Write the Docs: Christine Burwinkle – Pairing with designers to create a seamless user experience

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.

Christine works at Atlassian, makers of Jira and other software tools for software developers. Their design team has grown from 5 to 30 over the last couple of years. On the whole Atlassian has focused a lot on the user experience of their products. Traditionally their tech writing has played a more formal or traditional role. They saw an opportunity to work together toward shared goals. Both are trying to reach users and give them a really great experience, they just use different tools.

A few of the design principles the docs team brought over to their work were to be familiar, to grow with users, and to give clarity to users. Those drive the decisions their design team makes. They realized those goals are easily adapted to documentation. Personas also play a role for both their design and docs team. The design team did a yearlong project to develop those personas. These make it easy for different teams to have common ground in how to build their software for their users.

The docs team realized in this process that designers have access to lots of customer information. They have interviews, site visits, usability tests, usage information on existing features, and a long-term roadmap for the product. All of that can help a docs team build documentation that’s relevant for users.

The documentation process for Atlassian starts in user testing. Designers test new prototypes with users and the docs team uses information from those tests to guide their documentation edits. They piggyback analytics on to this for hard data as well.

The first tool the docs team borrowed from the design team was empathy maps. Empathy maps help bring focus on the user. You can use them to workshop how a user might feel in a “before and after” situation. You take the “after” situation and work backward.

Another tool they’ve borrowed is sparring sessions. They’re basically a critique session that brings group thinking in to design and planning. It’s a check that the goals have been met with a given prototype. The goal is to assure design quality by critiquing design early and often. Prior to a sparring session they send out a draft of the doc as well as a brief or outline that covers the goals of a document. A few tips they’ve learned the hard way:

  • Timebox, timebox, timebox! Set a timer so you don’t go down rabbit holes.
  • If your team is given to negativity, try a positives-only 5 minutes.
  • Try to make sure everyone is heard. You can use a checklist or give everyone 1 minute to list feedback.
  • Leave with at least 3 action items. The onus is on the writer to take action on these things.

6-ups are another workshopping tool they’ve borrowed. They drive focus on ideal solutions and get you out of “word-thinking” and can be a good way to build on each others’ ideas. Sometimes the best way to communicate an idea is to sketch it and really illustrate what a user will be seeing for a given feature.

User stores are an additional tool. It’s about figuring out how a user is going to go through a product. It charts a path through goals and actions within a product. Going through that path can help you spot where users will hit pain points and fall out of the flow.

They made all this happen by finding the right projects. They looked for a team that finds value in design and writing as well as a designer who sees the value in docs. It helps to look for a new project that’s running lean and has some momentum. Projects that are data-driven are also beneficial as it helps cement and validate the work you’re putting in to these sessions.

Write the Docs: Sebastien Goasguen – Going from Publican to Read the Docs

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.

Sebastien was the first talk after break. He works on Apache CloudStack and is a committer to the Apache project.

Apache CloudStack moved from an old documentation tool, Publican and DocBook, to Read the Docs. They wanted to bring in a greater sense of community with their documentation and make it more accessible.

The old tool, Publican, is a build tool for documentation written in the DocBook format. DocBook itself is a XML schema suited for books and papers; it’s not necessarily meant for web-based docs. The editing tools, though, are either technical like vi or expensive. For an open source project that’s a no-go. They were also running in to issues around localization, internationalization, hosting, and attracting new writers.

Using Read the Docs they were able to move toward using reStructuredText for writing. It’s an easy-to-read, WYSIWYG plain text markup syntax parser. The problem, though, is that they had 40,000 lines of XML to transform in to reStructuredText. Their lifesaver was pandoc. This let them convert all the files without needing to rewrite everything.

Sphinx allows them to build their documentation sites and projects. The hosting is handled through Read the Docs. One of the killer features for them was the button on each doc that let people edit on GitHub. Given that Apache CloudStack’s goal was to increase their contributor base this was vital. It dropped the barrier to entry for new contributors. They’re now starting to see drive-by contributions to docs, which is great.

The one last hurdle for them is translation. With large communities in China and Japan it’s key for the project to make translation easy. Handily, with Sphinx, they can do this. They use the same tool that Markus talked about yesterday. They now have more people contributing translations than they do documentation.

Ultimately changing documentation format gave Apache CloudStack docs which were good looking, easy to contribute to, supportive of localization, and much much more.

Write the Docs: Robert Lehmann – Self-Directed Learning Material

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.

Robert focused on how to write good learning material. We all suffer from ed-tech amnesia, in Robert’s words. There’s a huge body of research on how to teach people and how they learn material. In researching this talk he found that while there’s a huge body of material it is wildly arcane to us as technical people.

Robert works at the Open Tech School where they work to teach students programming. The workshops are done collaboratively with lots of hands-on coaching.

The first step in learning and collaborating is defining clear goals. You need to know where you want to go with the material; beginning with the end in mind helps greatly. There’s a difference between tutorials and references. References may seek to exhaustively document an API while tutorials consciously explain a single concept with an end goal defined.

Collaboration, though, can kill cohesion. With many people involved you have to actively protect the scope of learning material. At the Open Tech School they have someone who acts as the champion of learning documentation and they seek keep work tied closely to learning objectives.

When you use the right tools and lightweight markup you can lower the barrier to learning. For the Open Tech School this means using Jekyll and hosting files on GitHub Pages.

One thing that they haven’t found a good solution for is dealing with dependency hell. When teaching people how to code you run in to issues where the prerequisites for solving a given problem can involve setting up handfuls of other, irrelevant, dependencies. When teaching kids they’ve tried using system images that bundle those dependency requirements so students can write code and have it run right out of the box, mostly.

Another thing they have struggled with in their material is the amount of repetition. Repeating things is good, but at the same time you want to be concise so that students don’t skip over repeated material.

One guideline that is extremely useful for new coaches is to tell them the keyboard of students is made of lava. Too many new coaches cannot suppress the impulse to just fix one thing for the student. The problem is that this disrupts the student’s flow and attention. On top of that nudging new coaches to use socratic questioning can greatly help. Your students will benefit if you don’t just give them the answers.

At the Open Tech School they’ve found that feedback is great but that it’s mostly positive from students. Instead they focus on asking the coaches for feedback on where students struggle. It helps them spot the gaps and shortcomings in their documentation and learning material.

Finally, they’ve published all of their coaching guidelines.

Write the Docs: Jessica Rose – Tone in Documentation

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.

Write the Docs: Jannis Leidel – Search and find. How we made MDN discoverable

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.

Jannis is a developer working at Mozilla. He’s currently working on the Mozilla Developer Network, a site that covers the web platform, desktop app, Android, and Firefox OS efforts at Mozilla. There are 5.5 writers and 6 developers, as well as 14,000 community contributors, working on MDN and the site gets around 2 million unique visitors per month. With 900 live code demos and 33,000 wiki documents which have 375,000 edits in total there is a lot of content to deal with.

They now use kuma, a django-based wiki that’s available on GitHub. In the past, though, MDN ran on DevEdge, an AOL creation for static page sites. After a couple iterations they ended up writing their own software for documentation. That project became kuma. In 2013 they designed the site to bring a responsive layout with content zones that places search front and center.

Screen Shot 2014-03-31 at 2.40.27 PM

The emphasis on search, though, requires a powerful engine behind it. MDN has moved from a custom Google-based search to rolling their own implementation. It’s a full-text, multilingual search engine that provides faceting, filters, and pagination. The filters cover topics, skills, and document types. They can be dynamically changed based on what the Mozilla team sees in usage. Growth in certain areas allows them to emphasize different areas. It keeps the documentation responsive to the community’s demands and interest.

Each search page is also available as JSON. The users of MDN are developers themselves and this gives them the ability to use the data in formats other than MDN’s main site.

Another piece of MDN are the documentation status pages. This allows them to show the thousands of community editors and contributors what to work on first. It shows which pages need tags, editorial reviews, or technical reviews.

Firefox also ships with command-line access to MDN as part of their developer tools. From within the browser you can use the search API to pull up developer documentation. Users don’t have to leave to another site to find answers. In the future they want to extend this to plugins for popular code editors.

Write the Docs: Thomas Parisot – README Driven Development

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.

Write the Docs: Markus Zapke-Gründemann – Writing multi-language documentation using Sphinx

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.

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.

Write the Docs: Idan Gazit – Advanced Web Typography

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).

Write the Docs: Shwetank Dixit – Challenges and approaches taken with the Opera Extension Docs

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.

Write the Docs: Kelly O’Brien – Engage or Die: Four Techniques for Writing Indispensible Docs

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.