Heidi Waterhouse

BIG CONCEPTS small docs. User documentation is a failure of user interface. Faster and cheaper than making your developer write it. Elegant writing saves money. Paid by the anti-word.

Why are there no documentation bootcamps or schools?

—

by

Heidi Waterhouse
in ,

Sarah Mei and Sarah Fox and some other people and I were talking on Twitter about code school graduates, and how they frequently do really well at mid-level positions because they have communication skills from their previous careers.

We all agree that teaching someone to write well enough to be a Professional Technical Writer is more than you could cover in a six-week intensive, probably. Depending on where they start. I could absolutely turn a motivated journalist into an entry-level tech writer in 6 weeks. They’re 3/4 of the way there already. But most people would need to learn the following from scratch (in no particular order):

  • Audience analysis
  • Task-based writing
  • Procedural writing
  • User story writing
  • Error writing
  • Bug writing
  • Conceptual writing
  • Diagrams, illustrations, and screen captures
  • Rudimentary tools use
  • Sentence construction
  • Bullet point use
  • Theory of simplified English
  • Accepting editorial feedback
  • Accepting technical feedback
  • Elements of information architecture and presentation
  • Elements of usability and accessibility
  • Style guide use

Even if you’re coming out of a liberal arts/literary background, half of that list is something you may never have heard of. You can construct a great sentence, and you know how to use a semicolon, but your experience to date has rewarded you for things that don’t matter at all in technical writing. You’ve gotten good grades for making persuasive arguments or writing pithy literature reviews, but no one in my English Lit classes ever told me that I was addressing the wrong audience or designing my headings badly.

So that’s a daunting list of things to try to cram to get people into what is, let’s face it, a less glamorous profession than Code Warrior. I happen to think it’s the best and most influential place to be in a development team, but that’s not what the pay scales say.

That said

That said, I think I could do a LOT with teaching code school students and other developers some really basic writing skills. I tried this out at a Workshop at Write the Docs this year, and it went pretty well. I’d love to present it elsewhere. I’m putting the outline below the cut, if you’re interested.

Give me your developers for a day, and I’ll teach them to write a well-constructed error code and a readable bug report and a coherent status email. Give me two days and I’ll teach them about audience and analytics and deletion.

I want to do this for code schools, so we can catch people when they are frantically learning, so they will remember to look it up later. I want to do this for open source projects, because it is so hard to find or hire a technical writer. I want to do this for conferences where junior developers are looking to elevate their game. I have been traveling around to developer conferences for several years now, trying to distill everything I know from 20 years of my career into something that has value for coders, and I am convinced it has value.

Making words

Research basics

  • Who am I writing for?
  • What do they need to know?
  • How can I find that out?
  • How can I explain it?
  • Who can help me?
  • Who can check my work?

Writing basics

  • Make your sentences short and impersonal
  • Use graphics for concepts, but avoid screencaps
  • Use style guides and linters if you can

Using templates to write

  • Templates organize your thoughts and keep you from forgetting things
  • Templates add a standard look at feel at low mental cost
  • More like madlibs than “writing”

Organizing words

Every page is page one/search-first writing

  • If you don’t answer the question, or at least point to it, you’ve failed
  • People are seldom looking to grasp the whole concept
  • Search terms are precious gold 

Indexing and search

  • All the words present are indexed
  • None of the words missing are, unless you make an effort
  • We don’t all use the same words for things, especially in technology

Semantic tagging and re-use

  • Semantic text is separating the content from the form
  • Semantic tagging attaches labels to little bits of content – text objects
  • Reuse means that you don’t have to make the same change dozens of times
  • Reuse also means that there is overhead inherent in your documents. You have to compile.

Sorting topics into buckets

  • Even with search, you need to have some kind of structure
  • Group things together by how and when the user experiences them, not programming
  • Putting like things together lets people find what they actually want

Links, menus, and flow

  • Give people a next step
  • Provide related information links on the same page
  • Tell them where they are in the document with breadcrumbs
  • People think of things differently. Some people have to understand relationships

Distributing words

Static sites

  • Easy to get
  • Easy to maintain
  • Limited control

Hosted sites

  • Someone else sweats the hosting
  • More control over access by users
  • Less control over access by you

Baked in to your product site

  • All the worst features of both

CMS/Knowledge base articles

  • Useful for a community that knows what it wants
  • Prone to aging out
  • Sometimes diverges from published docs

Professional writing tools

  • So shiny and powerful
  • Learning curve like a brick wall
  • Seriously, it’s an IDE
  • Multi-client single source, variables and wacky stuff

Paper-ish things

  • Essential for some things
  • Reassuring to some people
  • Touch is a sense we can bond to

Using templates to publish

  • Unified look and feel
  • Consistency

Collaborating on words

Using templates as an invitation

  • Less scary than a blank page
  • Sets expectations
  • Encourages multiple writers

My one weird trick

  • Write what I think
  • People love to tell you you’re wrong

How to structure a hack day

  • Set a goal of things to delete
  • Set a goal of things to fix
  • Keep track of things you don’t have time to handle today

Deleting words

Why to delete

  • Old stuff is wrong and terrible
  • Wrong stuff hides the right stuff
  • Antiwords leave space for people to learn and think

How to delete

  • Temporarily
  • Based on analytics
  • Ruthlessly