Write The Docs EU — Shwetank Dixit – Challenges and approaches taken with the Opera Extension Docs

Image

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Cake or Death? Variations: Easy option or another easy option?

Goals:

  • Easy to understand.
  • Explain common use cases for developers.

Identify scope for improvement.

What helped? If you run into hurdles, document solutions that you find.

Scope of Improvement

  • Unified architecture explanation.
  • Easy to follow tutorials.
  • Explain common use cases.
  • Simple sample extensions.

His process:

  • Look at internal and Google Docs.
  • Note down what’s missing, and what works.
  • Think of common use cases.
  • Make sample extensions for those use cases.
  • Document issues he came across.
  • Write article explaining API, common use cases, and sample extensions.

Tools used:

  • Markdown for tutorials. Much love for Markdown. 🙂
  • API docs in plain HTML
  • Built with Jekyll
  • Available on GitHub

Attribution and Licenses: Creative Commons!

Right type of sample code and sample extension? Make it super simple, almost like a test case.

Sometimes, “the readers are teenagers!” 🙂

Thoughts on feedback. Multiple channels of feedback are good. Most weren’t through technical means, like a GitHub pull request. Also, there were abstract (“pie in the sky”) scenarios.

Ways they can improve their docs:

  • Navigation
  • Idea: Boilerplate extension generator
  • Increase awareness
  • Translations
  • Tweak the tone

His key points:

  • Empathize
  • Have a greater insight on your audience.
  • Make sample code and extensions before you write the tutorial.
  • Be as simple as possible.
  • Have multiple channels for feedback.

Write The Docs EU — Kelly O’Brien — Engage or Die: Four Techniques for Writing Indispensable Docs

Kelly O'Brien

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Engage to earn readers’ trust.

  1. Understand where they’re coming from.
  2. Sympathize with their frustrations.
  3. Know what they need to accomplish.
  4. Help them solve their problems.

Death by Apathy. Our readers are like teenagers. Write with empathy to prevent apathy. What’s important to them? (Spoiler: It isn’t about how the system is set up.)

Technique #1: Put your readers first. Build a mental picture of the reader.

Death by Alienation. Readers are sensitive. Don’t talk down to them, or they’ll ignore you.

Technique #2: Mind your tone. Formality. Balance of an authoritative and relaxed, conversational voice. Consider the company culture, purpose, and tech savviness of your readers. Be deliberate and consistent so they can see that you sympathize.

Death by Impatience. Don’t make them hunt for answers.

Technique #3: Lead with the problem. Make it clear to your readers what they’ll learn from each portion of your docs. Remind yourself:

“If I read this, what’s in it for me?” (WIIFM) This is also the secret to reader engagement. Add this to the beginning to each section later in the writing process.

Death by Disorientation. If your reader wonders, “Why are we talking about this?”, beware.

Technique #4: Use Powerful Pointers. “Key sentences that recap, state, or foreshadow the information you’re presenting.” Or, more formally, contextual structure. Avoid a “monolithic flood of information”.

These pointers for your readers:

  • Their needs come first.
  • They aren’t alone.
  • Communicate WIIFM to them.

Attending Write The Docs EU

I’ll be in Budapest with several Automatticians for Write The Docs EU, which is:

a two-day conference focused on documentation systems, tech writing theory, and information delivery.

It’s fantastic that WordPress.com is sponsoring it, too. 🙂

Andrew Spittle published his notes last year from Portland—with the tag “Write The Docs“—after every talk. If there’s a WiFi connection, and my brain is functioning, I’ll aim to do the same.

If you see me, say hello!