Amanda Olsen

Front End Developer User Experience Enthusiast

Blog

Thoughts on the industry

Best Practices for Automated Communication

Ordered from most-important to least-important

Macro: Groups of documents, processes

Make documentation part of every story.
a. This is how we keep docs up to date.

Build a hierarchy
a. It does not matter how good your content is if no one can find it.
b. Do not rely on search. Your navigation should be good enough to find things.

Remove everything that is not contributing
a. Anything that is not contributing is in the way.
i. Speed matters.
b. An old doc is worse than no doc because it reinforces the belief that docs are worthless.

When someone asks something already documented, send them the link to that doc.
a. Don’t answer their question.
b. This reinforces the Best Practice that users should read docs first and ask questions second.
c. And your document will likely say it better than you can say it anyway.

Do not store valuable information in wiki comments.
a. Comments, at the bottom of a wiki page, are meant for conversation only not for storing valuable information.
b. Once you learn something valuable, find the spot on the page where that content goes and add it.

Micro: Words, sentences, paragraphs

Don’t Repeat Yourself (DRY)
a. Just like we keep our code dry, we keep our docs dry.
b. Say what you need to say in one place only and then link to it as needed.

Be concise
a. Speed matters. Don’t slow me down. I don’t want to be reading your document to begin with.
b. Remove all unnecessary words. Less is more.

Be as specific as possible. Always.
a. Speed matters. If you’re not as specific as you could be, I have more thinking to do, which slows me down.

Be consistent
a. Don’t talk about “API devs” and later “server side devs”. Pick one! And use it! Every single time.
b. The text in a link should exactly match the page header on the next page.
i. Example: If I click “Tools & Access”, the page header of the next page should be “Tools & Access” not “Required & Recommended Tools”

Prefer lists
a. Prefer lists over paragraphs.
b. These are scan-able which increases speed of reading. And it’s all about speed.

Chunk content
a. Each new chunk requires a header, of course.
b. This also increases the scan-ability of your content. Brilliant!

Avoid nominalizations
a. “Use and Contribute” instead of “Using and Contributing”
b. “Include GC on your page” instead of “Including GC on your page”

Start most phrases with a verb
a. Usually applies to headers and list items.
b. “Setup Lodging spinner” instead of “Lodging spinner setup”
c. “Format a Pull Request” instead of “Pull Request Format”

Use active voice
a. “We use Yarn to install and manage…” instead of “Yarn is used to install and manage…”
b. “We configured Gulp to…” instead of “Gulp has been used to…”

Prefer simple language

Don’t be polite
a. If you ever see the word “Please”, delete it! Now!
b. If you ever see “you can”, delete it! Now!
c. “Install nvm and then use it to…” instead of “Please install nvm and then you can use it to…”

Avoid noun strings
a. “NASA is still developing the module that will provide living quarters for the astronauts aboard the International Space Station” instead of “NASA continues to work on the
International Space Station astronaut living-quarters module development project”.

Avoid formality
a. Write the way people talk. This decreases the reader’s processing time; it’s all about speed.
b. “You must” instead of “One must”.

Context

These Best Practices come directly from the ideas below.

Know Your Audience

  • Readers don’t read, they “satsfice” (satisfy + suffice).
  • The reader is trying to get something done; your document is only a means to an end; in fact, your document is in the way.
  • Nobody wants to be reading your document.
  • Nobody wants to update your document.
  • If the reader loses faith, he will not come back.
  • If it’s too much work, the reader will quit and not come back.

Principles

  • An old doc is worse than no doc because it reinforces the belief that
  • docs are kinda worthless.
  • Anything that is not contributing is in the way.
  • It doesn’t matter how good your content is if no one can find it.
  • Build your hierarchy. Maintain your hierarchy. Honor your hierarchy.
  • Love your hierarchy. Cherish your hierarchy. Take vacations with
  • your hierarchy.
  • Remember the Golden Rule: how you treat your hierarchy is
  • how it will treat you.

Resources

Share your thoughts

Your email address will not be published.


3 + four =