Write More Better: Tech Writing for Developers

Speaker: Elliotte Rusty Harold
Google

For more blog posts, see The Oracle Code One table of contents

General

• In user testing, the first thing people do is google how to do the task.
• SEO: want the first hit to be your doc page for the task.
• Developers use Google, read Stack Overflow, buy O’Reilly books that tell them about docs.

Tech Writer Specific SEO

• Learn abut general SEO
• Delete old docs so they don’t show up in search
• If want old docs available, archive at different URL and make sure the URLs search engines have points to the latest

Links

• Good for search engine juice
• Bad for users
• Assume some users follow every link and get lost.
• Every link loses 1% of users
• Inline links lose 10% of users
• No one reads the sidebar
• The only good place to put links is the bottom

Readers skim

• Leave out the boring parts – try to write the most important parts first and see if you need more.
• Code samples are critical
• Bulleted and numbered lists are excellent
• Use headings and whitespace

Writing for developers

• Developer casual mode
• Straightforward but not stilted
• Not too personal. Be comfortable, but not too familiar. Helps for international readers where might be less comfortable
• No jokes
• Avoid culturally specific examples (ex: baseball)
• Clear/concise/simple prose
• Short sentences
• One thought per sentences
• Itemized lists are good. Numbered lists are better
• Use present tense by default. Use simple past/present for specific past/future events.
• Use active (not passive) voice. Clearer because obvious who is the “doer” of the action.
• “You” for tutorials; “it” for references
• I/we are ok for war stories and case studies
• Simple words
• Omit needless words

English skills

• Aim for an eight grade reading level (except for technical terms)
• “Your reader’s English is much better than your high school French” – However, still not native speakers
• The people you work with and who attend English language tech conferences are not a representative sample.
• Easier to write simpler English then read harder English

Words to avoid

Can search your text for these words for ideas of what to make clearer

• Use to
• Tends to
• In order to
• Is able to
• Just (and other unneeded adjectives) – want adjective to clarify. If nobody would ever say the opposite of the word, it doesn’t mean anything.
• Please note that

Design

• How much of page is fluff? Headers/sidebars
• Header should scroll off page once page down. Wasted space when sticky
• Watch out for chart junk
• Videos are an addition to your docs, not a substitute. Some developers love videos; others will not watch them.

Productivity

• Write fast; edit later. Ok to use sentence fragments, “screenshot will go here”, link is xxx.
• Outline in headings/bulleted lists. Then expand later.
• Include docs in pull requests
• Put doc tasks in agile tracker
• Make sure all docs don’t fall the to person with the title “tech writer”
• Let coders write. Some will be better than others.
• Make sure low effort to publish

Feedback

• Make corrections easy – feedback link, file bug, edit this page. [I like when you can submit a pull request for the doc fix to an open source product]
• Have two feedback links – doc comments and product comments. That way goes to right area
• Good example: Maven has a “?” link where you can click and git will automatically fork for editing/pull requests. Can do everything in a browser.
• Use a plin text format (HTML/Markdown) vs Word/Google Docs/PDF to ease editing.

References

• Google Developer Docuentation Style Guide
• O’Reilly word list and style guide

My take: Excellent session. Some were things I’ve heard a million times. But I also learned a bunch of things and came away with ways to make books, blog posts and wiki pages clearer. I especially liked the before/after of sentences.