Website: Checklist for technical writing

Mentor

The mentor for this issue is @Sophie-Pages.

Task

The goal is to create a checklist for reviewing someone's work or our own work as technical writers.

Outcome

A new page should be added in the reference section of the Open Documentation Academy website.

Resources

• Contribute as a new contributor: Our how-to guides to contribute.
• Example: One of our previous pull requests adds a page in the website. It was for a different section of the website, but it's still a good issue to review.
• Write a good reference: Review the Diataxis framework.
• Follow the Canonical's style guide

Learning

• Learn how to contribute and work with git
• Create a reference
• Learn about the editing process for technical writers

Notes to get you started

I have the following text that you can use and improve to create the issue. Feel free to modify it as needed.

Title = Checklist for technical writers When it comes to peer reviews, it can get confusing and overwhelming at times because you want to be effective, but at the same time there can be many things to check. Consider using this checklist of things to keep in mind when doing peer reviews or editing your own work:

Content

Purposeful

• Goal of the document is defined
• Audience is identified

Completeness

• Prerequisites are defined
• Next steps are defined
• For tutorials and how-to guides, all the steps are present
• For installation guides, uninstallation steps are included

Accuracy

• Technical terms are defined where they first appear, or linked to definitions
• Links are relevant and functional
• Code snippets are relevant and functional
• Claims are backed by references/citations
• Primary documentation or reputable sources are used whenever possible

Clarity

• Language is clear and audience appropriate
• Examples are relevant
• Use active voice
• Topics are covered in a logical progression

Consistency

• Style guide is applied
• Headings and subheadings are stylistically and structurally consistent
• Use of terminology is consistent
• Punctuation and capitalization are consistent
• Template is followed

Form

Accessibility

• Contrast has been verified with an accessibility tool
• Non-decorative images or diagrams have an alternative text (alt text)
• Complex images and diagrams have an associated descriptive text
• Language used doesn't reinforce biases
• Best practices are followed for hyperlink text

Brevity / Conciseness?

• No unnecessary sentence left
• Headings and subheadings are short

Formatting

• Images or diagrams are used effectively
• Lists or tables are used effectively
• Examples are used effectively

Structure

• For tutorials and how-to guides, steps are presented in a logical sequence
• No wall of text left
• Links are at the end of the document when possible

Tone

• Tone is consistent throughout the document
• Tone is consistent when compared with other related documents

Spelling and grammar

• No spelling or grammatical errors
• Same language is used throughout (e.g. UK vs US English)

Information architecture

• Limited depth (no more than 4 to 5 levels)
• Documents are easy to find
• Information architecture is organized and coherent
• Consider the entire documentation set when adding, removing, or modifying content

Other?

Maintainability

• Document is easily maintainable and don’t propagate bad practices