Tag: Write the Docs

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

Write the Docs: Kevin Hale – Getting Developers and Engineers to Write the Docs

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.

Kevin was the next talk in the afternoon. Also, check out my notes from UserConf for notes from his talk there. He talked about Wufoo.

The ease of use Wufoo has means that, well, just about anyone can use it. Every person on their original team of 10 people wrote documentation. The secret, as Kevin puts it, was that everyone was working in customer support to some extent. They sent about 800 support emails a week to a user base of about 500,000.

Wufoo sought to create software that people had a relationship with. They were fanatical about creating meaningful relationships. They approached new users as if they were dating them and existing users as if they were married to them.

When it comes to new users, first impressions matter. The homepage, landing pages, plans/pricing, login, and support are the typical first impressions. Kevin prefers to focus on things like the first email, the login link, the first support interaction, and other specific pieces of the customer experience.

One way this looks in practice is how Chocolat allows you to keep using all the features after the trial period. Only thing is they force you to code in Comic Sans. Little touches like that matter.

Kevin also mentioned the site Little Big Details which collects lots of these kind of touches. WordPress is even in there. 🙂

Kevin mapped common marriage issues (money, kids, sex, time, others) to product issues (cost, users’ clients, performance, roadmap, others). As he put it, “divorce is like churn in a marriage.”

Kevin and the founders of Wufoo sought to create a support-driven development process. The way you make this work is simple. You just make everyone do customer support. The creators become the supporters and, thus, can’t ignore the things that cause users grief. This helped Wufoo scale their customer growth without causing an exponential hit on their support volume.

They learned a few lessons from this:

  • Support-responsible developers give the best customer support.
  • Contextual documentation is key. For example, clicking the “Help” tab takes you to the portion of docs for that feature.
  • Engineers who do support run experiments. Wufoo did this by having an emotional state drop down to their contact form.
  • Support-responsible developers actually create better software.
  • Support-responsible developers respect the people who do support full-time, every day. Their first full-time support person was revered because everyone understand what that job was like.

They spent 30% of their time in internal tools. As Kevin put it, some of the best software they created was stuff that no user interacted with. It’s wroth taking care of the stuff your employees work with every single day.

The prevent their user relationship from atrophying Wufoo included a “Since you’ve been gone” view in their application. Each time a user logged in they’d see a timeline of what features had recently been added. To be included in this list they required developers to have finished the documentation. So if a developer wanted their feature in front of every user, they wrote docs.

Kevin also posted his slides over on Speakerdeck.

Write the Docs: Leah Cutter – Generating a Culture of Doc

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.

Leah kicked off the afternoon sessions by talking about how you can encourage engineers to do the “write” thing. She focused on discussing the ideal. Not everything she covered will work but it’s a starting point.

Leah is a technical writer who is a Knowledge Management Specialist at Salesforce. She’s been working as a technical writer since 1985. As she phrased it, it is her job to generate a framework for engineer-generated content. She tells engineers what it is they have to write, where they have to put it, and what it should look like.

This engineer-generated content includes code comments, README files, specs, team sites, wikis, email announcements, and much, much more. You’ll notice external, customer-facing documentation is not on that list. That’s intentional.

By primarily focusing on internal processes you can create a culture of doc in your company and among the engineers.

Writers are outnumbered by engineers. Even at a documentation-strong company like Salesforce writers are just a small fraction of the workforce. By getting them involved you increase your ability to document things.

Within a company your knowledge exists in the minds of subject matter experts. These are frequently engineers. To be successful you need to get it out of people’s brains and in to text. When the knowledge doesn’t live in someone’s head it means someone wrote it down but you may not know where it lives. This causes the next problem, organization.

Salesforce, in part, solves this by having an entire team dedicated to internal documentation. They handle the internal architecture, processes and knowledge sharing across the company. It’s a 7-10 person strong team. A lot of this is code documentation as Salesforce is a monolithic piece of code. Some of the other docs are around building out data centers, servers, and more.

Even if your company won’t ever create an internal documentation team there are things you can do. Leah gave some ideas for how you can start generating useful processes and tools. The first step is finding the people around your company who are like-minded people. Seek out those people who care about documentation and give them a forum in which to participate.

Leah’s found that engineers break down between three roughly equal groups. Those who are eager to help, those who are willing to help but need guidance, and those who are curmudgeons.

One thing Salesforce does to motivate engineers to write documentation is hold internal documentation hack days. They kick it off with a talk, set clear guidelines throughout the day, and set a fun theme (e.g. “Doc like a pirate day!”).

The number one thing with creating a culture of documentation is to understand that some text is greater than no text. You have to start somewhere and anything you can create is progress. You can fix the text later; the first step is to get it written down.

The curmudgeons in your company will argue that good code documents itself. As Leah put it, good code only tells what something does, not the intent behind it.

Write the Docs: Virtual book sprint

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.

Bart talked about virtual book sprint. This stemmed from the X windows system which is one of the oldest window systems out there but has a very small developer base. About two years ago Bart decided to address this problem. He based it on Google Summer of Code sprints. Unfortunately getting people together in a distributed project with a small contributor pool is difficult.

They used Gobby to write docs up in Markdown. About 2 people put together 40 pages of developer documentation.

They learned a few lessons in this project:

  • Have enough people: People must be committed for the entire time. “Local pairs” would be a thing to try.
  • Have tools solidly in place and tested.
  • Nothing will happen after the sprint. Nothing.

Editing and writing are only part of the work. The tools and processes are also vitally important to the project’s success.

Write the Docs: A plea to Open Source Maintainers

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.

More technical writers need to contribute to Open Source documentation. There are recurring patterns of discouragement when writers try to get involved. Writers hear things like, “The source is self-documenting.” Or, “Oh, that code’s being rewritten.”

The single most common thing is just silence. That doesn’t help anyone.

Documentation can always be better, it’s never perfect. Open Source developers have other priorities than docs, that’s okay. Turning away English majors, though, misses an important opportunity. We can start a virtuous cycle where writers are involved and, thus, bring more writers to a project.

At a basic level, talk to a writer. Figure out how best you can work together. You can also organize a docs sprint. It’s a great way to start and accomplish a lot specifically with docs. On a more advanced level, you can mentor a writer. Be the veteran who can help introduce a writer to your Open Source project of choice.

Perhaps in the future we’ll have better living through documentation. It’d be cool to see a Summer of Docs at some point in the future.

Write the Docs: Jennifer Hodgdon – Motivating developers to write API documentation

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.

Jennifer is the API docs coordinator for Drupal. There are a few ways to get API docs written. First, no one writes the docs. This isn’t ideal. Second, you can hire tech writers to write the docs. This is only viable in a corporate project and may not even be desirable there. Finally, developers can write the docs. This is probably the only viable solution for Open Source. It’s probably desirable for most corporate projects, too.

When Drupal 7 came out about 2 years ago there was a lot of improvement in documentation. Jennifer submitted 278 patches which is awesome but not entirely sustainable. A similar trend held across the work in usability, accessibility, and performance in the project.

For Drupal 8, the method is to enlist the entire community in documentation. To do this a few things must happen. There have to be written standards for API docs. There also has to be a culture where bad documentation is treated as a bug. Finally, you need to create a culture in which patches without minimal docs are unacceptable.

Core gates in Drupal aim to solve the problem of getting to the end of a development cycle with code that has poor usability, documentation, test coverage, and more. To fix this all patches must pass through “gates” before commit. These gates are listed on the Drupal site. In practice it’s sometimes enforced and sometimes not.

The documentation gat means that all functions, classes, hooks, methods, and more have to have at least minimal API documentation. One line summary of what it does where all parameters are documented and the return value is documented. There are a few other aspects, as well, but that’s the core.

All API documentation for Drupal is embedded in the sourcecode. Having those separate will only lead to inconsistencies. You can still generate an API documentation site but the docs must live in the code.

Another neat thing they do, particularly with documentation, is use a “novice” tag for certain bugs. This is added to issues that are relatively easy for a novice user or developer to contribute to and patch. It helps bring in more contributors as well as get things fixed. They support this with Core Office Hours and a mentoring program that helps people get development environments set up.

Write the Docs: Sarah Grant – Evolution of the English Language from Text to Texting

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.

Sarah has mostly been a fiction writer and works for GeekGirlCon. The subtitle to this talk was, “Why the Oxford English Dictionary is My Favorite Book, and Why I Love the Chicago Manual of Style.”

The Oxford English Dictionary was expected to take 10 years. It didn’t quite work out that way. 5 years in they had gotten to the word, “ant.” The OED ended up listing over 50 million years.

NetLingo is a neat site for tracking the usage and meaning of newer, more text and web-native words. These can range from the mundane to the seriously confusing.

Some words, such as orientated, which we think to not be proper English are, in fact, listed in versions of the OED. English has been, and still is, a very fluid language. There is, essentially, no such thing as an unchanging rule.

Write the Docs: Matthew Butterick – Typography for Docs

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.

Matthew wrote (and gave out at the conference) a book titled Typography for Lawyers. Lawyers are, as Matthew put it, people who’s work largely depends upon writing, typography, and ensuring their readers are paying attention.

Before computers typesetters were some of the most complex machines around. Matthew sees computers and programming as a means of extending these early machines.

Matthew’s early foray in to programming was with C and writing a program for Macs that made kerning easier. This meant reading through a surprisingly thin book. As he put, “all the secrets are just right here!” He compared this to an AppleScript book that was 900 pages. As he put it, “What the hell requires 900 pages for AppleScript? It’s a piece of shit!” These long books do a horrible job of representing programming and fail at maintaining reader attention.

Typography is the visual component of the written word. If you’re putting words on a surface that will be read you are a typographer. It’s the presentation that defines typography.

The purpose of typography is not to make things pretty. It has a functional purpose and aims to conserve reader attention. Pretty may be a side effect but it not the sole goal. If someone stops paying attention you’re dead.

Matthew argued that the ease of digital publishing and the access of the web has, to some extent, made documentation lazy. The necessity of being concise and clear is not necessarily as present.

He pointed to a picture in his book (page 18) of the butterfly ballot from Florida’s election in 2000. As Matthew said, this horrible typography got us in to war. In other words, the idea that typography doesn’t have consequences is wrong.

Typography can draw people to a project or it can repel people. Take the earlier AppleScript story as an example.

The 4 things Matthew says you need to know about typography are: font choice, point size, line length, and line spacing.

The secret to typography is what the body text looks like. This is partly because there is more of it than anything else. In terms of font choice Matthew said, “when you’re using Arial or Georgia you’re sort of using the font of last resort.”

For point size he pointed out that 12pt type is not the world’s default size. Most printed material is set much smaller. The web inherited this as early screens had to be small in order to display a reasonable amount of text. With better screen technology we shouldn’t feel afraid to use larger sizes.

Line lengths are also frequently abused on the web. The ideal length is 45 to 90 characters and no more. A simple rule of thumb is that a line which can fit 3 full alphabets is too long.

120-145% of the point size of text is Matthew’s ideal range for line spacing.

Overall typography shouldn’t make users angry. But if you do it poorly, it will. Documentation is for reading and poor typography places a barrier between users and their goal.

Write the Docs: Erin Robbins O’Brien – Beautiful Documents – A Language Love Story

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.

After the morning break Erin started things off by talking about how to help you to continue loving what you do. As she put it, “documentation is not always easy but it’s always worth it.”

Remember why you loved documentation in the first place. For Erin that’s the look of a blank document, the curve of your favorite font, the ability to change the pace of an entire document with punctuation. Knowing the little things about language makes you the master of the language universe.

She included some tips for maximizing efficiency. The University of Virginia found that looking at cute images increases your fine motor skills. Harvard studies on productivity also show that facing your desk away from the window helps you stay on track. You should also try writing docs in a new font. A small change in style, even temporarily, can refresh creativity. Just don’t use Papyrus or Comic Sans. It also turns out that being warm, around 77 degrees, decreases typing errors and increases output.

You should also look at your docs through someone else’s eyes. Talk to students, interns, colleagues, and users who are looking at your document for the first time.

Also, always remember that before you wrote this document it didn’t exist. You are creating knowledge. That’s pretty cool.

Write the Docs: Michael Verdi – How Mozilla supports users all over the world

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.

Michael works on the SUMO project which is short for support.mozilla.org. He’s a content manager who works on projects affecting people on every continent. At any given time there are 200 or so “Mozillians” working on their support site.

The first part of the documentation process is proactive support. They set up a big force field around planet Firefox. As part of proactive support they focus on user advocacy (bug fixes, features, etc.) and education (experience, features, marketing, engagement, articles). Mozilla’s more reactive aspect of support includes self-service support and user-to-user support.

In terms of education they aim to link to support docs whenever possible, even on Firefox’s homepage. Every new release of Firefox also includes documentation. So with Firefox 20 the download manager changed and was released along with a how-to video that was sent to tech writers and press.

As Michael put it, “It’d be nice if we could write software that never broke.” In the meantime, we should make it easy for users to recover when there is a problem. Mozilla approaches this with, for example, a “Reset Firefox” button that aims to automate some of the preferences-related debugging you have to do. About 80% of the time this fixes their support issues.

Some things will get through the force field of proactive support. For that, Mozilla uses a tool called Kitsune. This is their knowledge base, support forum, Twitter client, search, internal communication, and metrics.

The knowledge base is what Michael focused on. They use fully localizable wiki-based documents that support multiple products across multiple versions and operating systems.

The multiplicity of docs was cool. It’s all done through special wiki markup that allows them to show platform and version-specific instructions and screenshots for a particular feature. That allows the document to much more directly speak to the user’s need.

They run a survey on each article to gauge its helpfulness. They’ll then plot the responses to this survey alongside revision history. It helps them draw a correlation between document changes and their impact on users. This data is then pulled in to their document dashboard which allows them to, for example, filter for unhelpful documents.

For their localization each untranslated article includes helper text that asks readers to get involved and help translate articles. It still presents the text in English in case that is helpful to the reader. Their tool for this shows the English on one side with the new, translated text, on the other.

The top 20 articles on Mozilla’s support site account for 50% of the traffic. The drop off after that is quite steep. Just the top 70 articles account for 80% of their visits. This makes translation much easier as efforts can be directed to those documents that are most-used.

With their 6 week release cycle they don’t mark any documents as ready for localization until 2 weeks in to the cycle. This, ideally, means that localizations only have be done once per cycle. Small changes after that 4 week mark will be made in English but, unless it’s critical, not marked for localization again.

Michael posted all his slides too, which is great.

Write the Docs: Kenneth Reitz – Documentation is King

I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.

Kenneth, who works at Heroku, kicked off the morning at Write the Docs. He started his talk by stating that, “Constraints foster creativity.” It’s about the simple things: prime lenses, mechanical watches, pen and paper, etc. In his code and documentation he aims for pragmatism and constraints. If you try to build something that works for everyone’s use case it causes a bad experience for all.

With Kenneth’s Requests tool, he took this approach. What makes a code package popular is the API. All other things are secondary. Developers spend hours every day working with your APIs. If you don’t put a high level of craftsmanship in to those products you’ll only be frustrating your most frequent users.

Documentation is what helps your API grow without becoming compromised. Before any code is written, write the README – show some examples. Then, you should write some code with the theoretical code that you’ve just documented.

Kenneth relates this approach to responsive design. A README-driven API design is responsive to the needs and use case of your users.

He quoted Pieter Hintjens who said that, “Simplicity is always better than functionality.”

Documentation is the glue that makes open source projects possible. As Kenneth put it, if you got to a page and don’t know what problem the code solves then the project has failed. Documentation helps you to explain what problem your code is solving.

Technical debt, code inconsistencies, and many other aspects of internal development issues stem from poor documentation. Both open source projects and internal code are essentially useless without documentation.

Documentation, for Kenneth, leads to better code, a better workplace, and a better lifestyle. It allows more asynchronous workflow where coworkers can dive right in to a new code project without needing to bother someone else about how the API works.