Month: April 2013

April 8, 2013

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.

April 8, 2013

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.

April 8, 2013

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.

April 8, 2013

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.

April 8, 2013

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.

April 8, 2013

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.

April 8, 2013

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.

April 7, 2013

Humanity’s deep future. Interesting survey of future-oriented human thinking. The bit on Konstantin Tsiolkovsky’s notion of a great filter is new to me.

April 6, 2013

I wish I had all my notes from college in plaintext Markdown-formatted files. As I get back in to reading more difficult texts I’m writing up chapter notes in nvALT.

The more I do this, the more I find myself going back to them and searching for previously noted phrases, definitions, or quotes. My reminiscent wish is for nvALT to be a single data store for all my reading annotations. The problem is I have all these NeoOffice and Pages files from college.

April 6, 2013

Peter Thiel’s CS183: Startup – Class 9 Notes Essay. A fantastic set of notes from Peter Thiel’s CS:183 class on startups. This session was specifically about distribution and Blake has 18 more class sessions worth of notes.