---
title: "Style and writing guides"
date: 2024-07-22
url: https://hackmd.io/h68Bay1VT-CA1etEsCegtA
---

## Style and technical writing

- [ISO How To Write Standards](https://www.iso.org/files/live/sites/isoorg/files/developing_standards/docs/en/how-to-write-standards.pdf)
- [IEEE Editorial Style Manual for Authors](https://journals.ieeeauthorcenter.ieee.org/wp-content/uploads/sites/7/IEEE-Editorial-Style-Manual-for-Authors.pdf)
- [IEEE SA Standards Style Manual](https://mentor.ieee.org/myproject/Public/mytools/draft/styleman.pdf)
- [IEEE Documentation Style: How to Cite References](https://ieee-dataport.org/sites/default/files/analysis/27/IEEE%20Citation%20Guidelines.pdf)
- [Google developer documentation style guide](https://developers.google.com/style/)
- [Google Tech Writing Course](https://developers.google.com/tech-writing)
- [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)
- [C++ Specification Style Guide](https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines)
- [Red Hat Technical Writing Style Guide](https://stylepedia.net/style/) ([src](https://github.com/StyleGuides/WritingStyleGuide))
- [Apple Style Guide](https://support.apple.com/guide/applestyleguide/welcome/web)
- [Mathematical Writing - Knuth et al.](https://jmlr.csail.mit.edu/reviewing-papers/knuth_mathematical_writing.pdf)
- [How to Write Mathematics - Paul R. Halmos](https://entropiesschool.sciencesconf.org/data/How_to_Write_Mathematics.pdf)
- [awesome-writing](https://github.com/jenniferlynparsons/awesome-writing) -- A collection of links on technical writing.
- [Mailchimp Content Style Guide](https://styleguide.mailchimp.com/)
- [Advice for Technical Writing](https://css-tricks.com/advice-for-technical-writing/) -- Chris Coyier
- [GitLab Technical Writing Fundamentals](https://handbook.gitlab.com/handbook/product/ux/technical-writing/fundamentals/)
- [UX Writing: Study Guide](https://www.nngroup.com/articles/ux-writing-study-guide/) -- Nielson Norman Group
- [Write the Docs](https://www.writethedocs.org/) -- Technical writing community
- [Wikipedia Manual of Style](https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style)
- [DigitalOcean Technical Writing Guide](https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines)
- [The Documentation System](https://docs.divio.com/documentation-system/) — Four types of documentation: tutorials, how-to guides, technical reference, and explanation.
- [Duke Graduate School Scientific Writing Resource](https://sites.duke.edu/scientificwriting/)
- [University of Oxford Style Guide](https://www.ox.ac.uk/sites/files/oxford/media_wysiwyg/University%20of%20Oxford%20Style%20Guide.pdf)
- [IBM developerWorks Editorial Style Guide](https://web.archive.org/web/20210126213122/https://www.ibm.com/developerworks/library/styleguidelines/index.html)
- [Salesforce Style Guide for Documentation and User Interface Text](https://developer.salesforce.com/docs/atlas.en-us.216.0.salesforce_pubs_style_guide.meta/salesforce_pubs_style_guide/overview.htm)
- [Rackspace Writing Guidelines](https://github.com/rackerlabs/docs-style-guide)
- [OpenStack Writing Style](https://docs.openstack.org/doc-contrib-guide/writing-style.html)
- [MongoDB Documentation Style Guide](https://www.mongodb.com/docs/meta/style-guide/)
- [Conscious Style Guide](https://consciousstyleguide.com/)
- [18F Content Guide](https://web.archive.org/web/20250402130753/https://guides.18f.gov/content-guide/our-style/)
- [Splunk Style Guide](https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse)

## Professional Guides

- [List of Style Guides](https://en.wikipedia.org/wiki/List_of_style_guides)
- [MLA Style Manual and Guide to Scholarly Publishing](https://www.scribbr.com/mla/formatting/)
- This is out of print, last published in 2015; it was replaced by the MLA Handbook that has a seemingly smaller scope.
- [The Associated Press Stylebook](https://writer.com/blog/a-comprehensive-guide-to-the-ap-style-of-writing/)
- [APA Writing Style Guide](https://en.m.wikipedia.org/wiki/APA_style)
- [The Chicago Manual of Style](https://library.menloschool.org/chicago)
- [The Gregg Reference Manual](https://www.amazon.com/Gregg-Reference-Manual-Desktop-Access/dp/0077514866)
- [A Dictionary of Modern English Usage (Fowler)](https://archive.org/details/modernenglishusa0000unse_a0n6/mode/2up)
- [The Elements of Style (Strunk)](https://www.gutenberg.org/ebooks/37134)
- [Archive.org](https://archive.org/details/theelementsofsty37134gut)
- [Project Gutenberg](https://www.gutenberg.org/ebooks/37134)
- [Garner's Modern English Usage](https://en.wikipedia.org/wiki/Garner%27s_Modern_English_Usage)
- [Webster's New World College Dictionary](https://archive.org/details/webstersnewworld0000unse_k1f4/page/n5/mode/2up)
- [The New York Times Manual of Style and Usage](https://archive.org/details/newyorktimesmanu0000sieg)

## Accessibility

- [Improve the readability of the content on your website](https://piccalil.li/tutorial/improve-the-readability-of-the-content-on-your-website/) -- Andy Bell
- [15 Practices to Improve Your Website Accessibility](https://websitesetup.org/web-accessibility-checklist/) -- Bruce Lawson
- [Accessibility Testing Tools](https://css-tricks.com/accessibility-testing-tools/) -- Chris Coyier
- [Why Don’t Developers Tke Accessibility Seriously?](https://css-tricks.com/why-dont-developers-take-accessibility-seriously/) -- Melanie Sumner
- [Naming things to improve accessibility](https://hidde.blog/naming-things-to-improve-accessibility/?utm_source=CSS-Weekly&utm_campaign=Issue-360&utm_medium=email) -- Hidde de Vries
- [Write the Docs Accessibility](https://www.writethedocs.org/guide/writing/accessibility/)
- [Write the Docs — Reducing Bias](https://www.writethedocs.org/guide/writing/reducing-bias/)
- [A11Y Style Guide](https://a11y-style-guide.com/style-guide/)

## Copywriting

- [Copywriting 101](https://copyblogger.com/copywriting-101/) -- Copyblogger
- [What is Copywriting?](https://www.ionos.com/digitalguide/online-marketing/online-sales/what-is-copywriting/) -- Ionos
- [SEO Copywriting](https://www.semrush.com/blog/seo-copywriting/) Guide -- Semrush
- [Copywriting is still writing](https://www.theguardian.com/books/booksblog/2008/jan/18/copywritingisstillwriting) -- The Guardian
- [Enlightened Use of Passive Voice in Technical Writing](https://ntrs.nasa.gov/citations/19820007101)
- [George Orwell: Politics and the English Language](https://www.orwellfoundation.com/the-orwell-foundation/orwell/essays-and-other-works/politics-and-the-english-language/)
- [Introduction to Microcopy](https://uxplanet.org/microcopy-tiny-words-with-a-huge-ux-impact-90140acc6e42?gi=9a63f9a33e8)

## Mason Egger Talk

[Mason Egger PyCon -- Write Docs Devs Love](https://www.youtube.com/watch?v=9WobKoE9OPI)

DigitalOcean docs are often praised for their quality.
https://www.digitalocean.com/community/tutorials

1. Make Your End Goal Clear

Have a clear, concise goal in your first paragraph.
Don't tell the reader how great the technology is.
Make it obvious what your reader will have learned, built, accomplished, understood, etc. by the end of reading the documentation.

2. Don't Be Overly Verbose

Be concise.
Use plain English.
Aim for 3rd grade reading level (up to 6th).

3. Use Inclusive Language

Avoid gendered language and pronouns.
Avoid slang that might be viewed as derogatory (noobs, 10x developers, dummies)
Avoid words that can make someone question or doubt their skills.
"simple" or "easy" might actually be a challenge for someone.

4. Limit Technical Jargon

Jargon — special words or expressions that are used by a particular profession or group and are difficult for others to understand.
Know your audience, assume beginners if you don't know.

5. Define Acronyms

Write out the full term when you first introduce it.
If you plan to use the acronym through the rest of the text, say so.
"We'll refer to the Domain Name System as DNS for the remainder of this tutorial"

6. Avoid Memes/Idioms and Regional Language

This goes back to "use plain English". Not everyone will be familiar with idioms ("costs an arm and a leg" "piece of cake", etc. Consider non-native speakers.

7. Use Meaningful Code Samples and Variable Names

Use real problems to solve.
Many readers will skip or skim the text and look at the code first.
Include everything needed to run the code.
Provide the full example of code somewhere.

8. Don't Make Your Reader Leave Your Docs

Don't send the reader to another site. You should have everything necessary.
If you must, put it at the beginning, perhaps as part of a list of prerequisites.

9. Make Your Content Scannable

Use Headings and Sub-Headings to break up content.
Use consistent style when writing.

10. Verify Your Instructions! Test, Test, Test!

Verify your instructions work.
Have someone else test your work.
Use a fresh environment for your testing.