Skip to content

Instantly share code, notes, and snippets.

View charlie-ac's full-sized avatar

Charlie Robinson charlie-ac

2 followers · 0 following
View GitHub Profile
@charlie-ac
charlie-ac / technical_writing_one.md
Created October 19, 2023 22:11
This compilation adapts guidelines from Google's Technical Writing One course into Markdown. The revision excludes elements such as exercises and videos.

Words

We researched documentation extensively, and it turns out that the best sentences in the world consist primarily of words.

Define new or unfamiliar terms

When writing or editing, learn to recognize terms that might be unfamiliar to some or all of your target audience. When you spot such a term, take one of the following two tactics:

  • If the term already exists, link to a good existing explanation. (Don't reinvent the wheel.)
  • If your document is introducing the term, define the term. If your document is introducing many terms, collect the definitions into a glossary.
@charlie-ac
charlie-ac / technical_writing_one_summary.md
Created October 19, 2023 22:09
This document outlines the guidelines from Google's "Technical Writing One" course. Pass the raw Markdown into an LLM to assess your writing against these guidelines. GPT-3.5 may not process the full style guide effectively, but GPT-4 performs well when provided with clear prompts.

Words

New or Unfamiliar Terms

  • Link unfamiliar terms to existing explanations.
  • Define new terms; group many definitions in a glossary.

Consistency

  • Use terms consistently throughout.
  • Shorten long-winded terms only after introducing them.

Acronyms

  • Bold and spell out on first use, followed by acronym in parentheses (e.g., Telekinetic Tactile Network (TTN)).
  • Use acronym consistently thereafter; avoid toggling with full term.