Key tips for quality, translatable, accessible content

1. Use concise sentences, minimalistic writing, careful writing.

2. Check broken links as you build content for preproduction KC.

3. Use Github to search for filenames if you change a filename.

4. Run the link checker on your files.

5. Request peer reviews for all new topics.

6. Run local builds and check spelling before you do a PR.

7. Use proper grammar and follow style specifications.

8. Use CHKPII to check PII compliance.

9. Run Acrolinx (Update on Acrolinx status at IBM–moved to individual teams instead of marketing).

10. Avoid HTML in .md file: causes translation errors and you can usually find a .md solution.

All these tips help to improve translation, readability, usability, and presentation.

Writing concisely and clearly

1. Analyze your sentence structure.

Examples:

First draft: Only users belonging to the certain role can view data belonging to a certain namespace.

Better draft: Only users who are assigned to a certain role can view data within a namespace.

Why? Belonging is confusing and can mean many things, and it is used twice. A relative pronoun is better used to connect a clause or phrase to a noun or pronoun. The clause modifies, or describes, the noun. The most common relative pronouns are who, whom, whose, which, and that. Sometimes when and where can be used as relative pronouns, as well.

2. Mood and voice (avoid subjunctive mood, write in active voice):

3. Wish, desire, please –- all of these are not concrete, not imperative

4. Should (rarely used, but needs clarification—make it must!)

5. Tense: Always strive for present tense.

Example:

If you were to save the file (not present, wordy, room for interpretations

If you save the file … (Clear, concise)

6. Use Active voice.

Links

1. Do not overuse embedded links.  Embedded links are links that appear mid-sentence or mid-paragraph. Such links are disruptive because the user must decide whether to go immediately to get the information.” If user needs lots of links, consider a section for references in the topic.

2. Name the link so that the user sees value in the title and can better decide whether to click or come back later.

Short descriptions

1. Use complete, but concise sentences.

2. Avoid self-referential language: “This topic…” (Although this is present in much of KC)

3. Don’t repeat the title.

4. Give the user a little knowledge in just a couple sentences about what the topic is about.

Quotation marks

As the style guide recommends, quotation marks are only for citations, which are rarely used in tech doc. Only use them if they are part of the command.