Tech Writing Guidelines

PREVIEW

https://algolia-tech-writing-guidelines.netlify.com/

What can you get from these guidelines?

A Short overview

• People using documentation have a right to find what they need, easily

• on the other hand, it's a 2-way street, technical writers can reasonably expect "good will" on the part of the reader

• It's a combination of a certain level of concentration ("good will") by the reader and a well-organized, well-written, and through documentation

How is it different from others

Goals of the content

Structure of the content

How to get started

Purpose of it being open source

Contribute

Github instructions

How to Run the site

For now: https://algolia-tech-writing-guidelines.netlify.com/

Official website: TBD

Content looking for a different page

Reasonable Expectations of Writers and Readers

• Documentation should communicate

• What are the obligations of the reader?

• Good will

• Willingness to (sometimes) read a sentence more than once

  • but this requires that our writing style is easy to read - that the second reading is done only because the reader is reading something they didn't know beforehand, or the subject is inherently complex and requires some thought, or the point being made is so important that rereading is ensuring memorization

• Readers should be able to copy code and see how things work

  • But this requires that we have easy to copy/undersand code snippets, and tutorials and how-tos are well-done

Relevant to every reader

The Docs must be readable / useable by everyone

Who comes to the docs?

• non-technical people
• junior-level beginners to the subject
• senior-level beginners to the subject
• experienced with the subject
• Product managers / Decision makers
• Stakeholders, people who will own a solution but not necessarily the developer
• non-anglophones
• Solo entrepeneur / Developer

Complete / thorough

• Every subject treated is covered completely - no aspect of a treated subject is not discussed
• Every subject necessary for the overall subject of the documentation is treated
• Every way of seeing that subject is covered
  • use case
  • reference
  • non-technical
  • technical

Sentences

• Sentences should be simple, straightforward
• Sentences should generally have only one idea, purpose, and meaning.
• It is acceptable to add implications to a sentence, such as the importance of the subject, whether it is recommended or not, if it is dangerous, serious, the potential impacts, but to not overload the sentence with too many meanings.

Word-choice

• Word-choice must be simple, well-defined, universally understood, consistent throughout

Paragraphs

• Paragraphs should be short and contain a single subject or a single aspect of a larger subject, and it should have a clear beginning and end

Pages

• Should be self-contained
• Should be focused on one purpose - to treat a full subject, to teach someone how to do something, explain a concept
• Should not do too much
• Should know its purpose, stick to it, and should know the limits of how much to include and whether the page needs to be divided into 2 or more

Sections

• Should be limited if not removed all together - stick with pages that cover a subject well, and hyperlinks + good navigation to complete a subject

Not Disjointed

• Content should be well-organized
• Information should not be scattered across too many different pages
• A single page should have a clear purpose and achieve that purpose without requiring a user to go elsewhere

Language guidelines

• We/You

• Future / Present

• Active / Passive

• Imperative

• Consistant use of hyphenating nouns (hands on, hands-on), 2-word phrasal verbs (checkout vs check out)

• Consistence use of login logon log on longged in or on

• Jargon

  • When, when not, if ever?

• Acronyms

Styling Guidelines

• Examples

  • All pages with examples should start with the most simple before getting more complex

• Bullet points

  • periods or not?

• hyperlink styling

  • punctuation as part of the link or not?

• Bolding

  • For what purpose
  • should be consistant
  • punctionation inside?

UI

• Sidebar on the left side?

• Sidebar on the right side

• Menu at the top

• Hover over

• Hide/show divs

Kinds of Pages

Navigation Pages

Wiki Pages

Single Subject - what, why, when, how-To

Multiple Subjects - what, why, when, how-To

Tutorials

Code Blocks - dos and donts

Imagery / Graphics

• Graphs
• Tables
• Schemas
• Illustrations
• Screen captures
• Drawings
• Cartoon characters
• Same look for all graphics

UI Design

User Testing

• Testing different titles, text

• Testing different entry points to the same content

• Tools

  • heatmaps, recordings
  • analytics

Organizational Flow

Reference Pages

Exisiting drafts

General guidelines

Tutorial writing guidelines

A short background

At the 2018 Prague Write The Docs Writing Day, a group of technical writers got together to discuss best practices for writing online documentation. We capitalized on the diversity of the group - from different countries, industry segments, and different readership. Below is our results.

Note: We cannot tell you how to do your job, nor do we think our results are the best or include all of the best ideas. Excellence should be scalable, and so if there is anything permanently true, it is that the best documentation is capable of improvement.