Peer editing checklist

The following checklist is intended as a spot check for peer reviewers. For more in-depth guidance on writing different kinds of topics for Open Liberty, see the other articles in this wiki.

Audience and readability

• Review the topic for user-centricity. Is the title feature-focused rather than user-focused? Make sure the content is focused on what the user is doing, not on what the feature or UI is doing
• What is the learning objective? Does the content support this objective?
• Use examples to make concepts concrete.
• Use present voice and active tense.
• Check that ordered and ordered steps are used correctly. Don't use ordered steps unless each step depends on the previous step.
• Use short, understandable words.
• Keep sentences concise and to a single thought.
• Keep paragraphs short.
• Avoid idioms, colloquialisms, and tough-to-translate phrases.

Technical verification

• Verify the doc against any existing source material that it is based on. Check for precise details that might have been overlooked.
• Verify that any source material is current and relevant to the audience and learning objectives for the topic.
• Check that all technical terms and product names are used correctly and consistently.
• Don't make product names plural or possessive
• If the topic is a task, make sure it has been tested and verified by an SME
• Don't reference or link to specifc versions of the runtime or a feature unless the concept or behavior that is being described applies to only certain versions. In that case, be clear about what information applies to which versions.
• If the content changes significantly since the SME review, send the doc back to the SME to verify its accuracy.

Accessibility

• Don't use directional language: above, below, left, right
• Make sure all diagrams, images, and graphics have alt text.

Formatting

• Identify abbreviations and acronyms and use them consistently.
• Link judiciously and make sure links are working.
• Use clear, consistent, descriptive link text.
• Put code text and values in monospace.
• Include a noun identifier for any code entities
• Make sure all tables have a title, descriptive introduction, and header row.

Headings

• Create headings that the user can quickly scan to find the information on the page.
• Check that headings are unique, descriptive, and parallel.
• Use gerunds in headings only in task topics.
• Always immediately follow a heading with paragraph text; never with a table, image or another heading.

Lists

• Start each list with a heading and introduction. Don't stack multiple sets of lists or steps in a single section
• Include no fewer than two items in a list.
• If your ordered list has more than 10 steps, consider breaking it into multiple lists.

Grammar

• Run Acrolinx before reviewing and after any substantial edits.
• Don't use Latin phrases or abreviations: "etc." "e.g." See
• Avoid expletive statements, unclear subjects, or pronouns, such as "This is..." "This means.." "It is important that..."
• Don't hide content in parentheses. Use commas instead.
• Don't use "(s)" to form plural nouns. Use the plural.
• Don't use "and/or". Use "or".
• Don't use the word "should".
• Use "between" when you discussing two things, and "among" for three or more.
• Don't say "we recommend..." Tell the user what to do and why.
• Be clear about what is optional and what is required. For options, say "You can...". For requirements, say "You must..."
• Remove all instances of "just", "simply", "even" and similar unnecessary words.

This list was adapted in part from The Product is Docs by Christopher Gales, c. 2020 Christopher Gales.