General Writing Guidelines

User Testing

• Google analytics
• HotJar
• Actual feedback
• Adding a feedback button to the bottom page
• integrating Discourse directly into docs
• Other way - +user testing reels that the app is not a good interface, is that a documentation question? or only a software team problem?

Media

Videos

• make a list of Time sequences
• captions
• presentations - webcasts
• “captivate” “articulate”
  • scripts
  • Learning Process

Team, Personnel, Expertise

Education Team

Communication

• Subject Matter Experts

On-boarding Documentation

• Handbook

UI Design

• Collaboration between Tech Writers and Designers

• Bullet points

  • periods or not?

• hyperlink styling

  • punctuation as part of the link or not?

• Bolding

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

Change Requests, Doc Updates

Github Alternatives to github google docs google forms

Language Guidelines

Language

• Plain language

• Jargon / Acronyms / Important Terms
  • List of words at the beginning
  • Should be used when necessary
  • Jargon that is company-specific / industry standards
  • User-centric
  • Tooltips
  • Glossary
    • UI question
  • Internal (workers in company) vs External readers - jargon is

• Slang

• We/You
  • Conversational
  • Leads to more active language
  • Release notes
    • “Fixed”
    • “versus formatted text”
• Future / Present
  • Present - Follows the thought process of the user
• Active / Passive
  • German language - formal language
• Languages - german, russian, english - different rules
  • Passive / formal for german
  • Translation issues

• Imperative

• Must / It is required

• Want / Need

• “Now you know …” at the end of a paragraph or page

• Tone
  • rust

• 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

Sentences

• Sentences should be simple, straightfoward
• Sentences should generally have only one idea, purpose, and meaning; but it is acceptable to add implications, such as the importance of the subject, whether it is recommended or not, if it is dangerous, serious, the potential impacts
• Sentence Structure
  • Same structure throughout?
  • Pattern for sentences (“In this window, on this button, …”)?
  • Tutorials, how-tos - more patterened than concepts?

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

• Release notes
  • What’s new
  • Why ?
• Short Paragraphs, one throught per paragraph

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