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