Writing style guide

Read this section to effectively write in a style consistent with other Learning Paths.

Content that deviates significantly from these guidelines will need to be revised.

Voice

Voice or tone describes the way something is expressed. This is different from describing the facts that you are writing about. The same idea can be described in a variety of voices, for example, formal or informal.

Learning Paths should be written in a clear, simple, and informal voice. You should write in a voice that anticipates the needs of your reader and is not pedantic or formal. However, do not write in a verbal style, as that is too informal.

If you write in a clear, simple, and informal voice, your content will be easy to understand.

Keep It Short and Simple

Use short words, sentences, paragraphs and sections. Avoid a long or complex word when a simpler, shorter word will make the same point. Conditional words are ambiguous. For example, instead of “could”, “would”, “should”, and “may”, use “can”, “will”, and “might”.

Use active voice

Use active voice. Active voice is direct. The reader knows what the subject and object of a sentence is, and the subject appears first in a sentence

Active voice: Software in external memory builds the MMU page table.

Passive voice: The MMU page table is built by software in external memory.

Use present tense

Use present tense because it is concrete. It emphasizes what the user can do now. And it uses fewer words.

Avoid jargon

Avoid overuse of adjectives. Avoid jargon including Latin abbreviations. Make content user-focused. Arm is committed to making the language we use inclusive, meaningful, and respectful.

Hyperlinks

Linking data allows readers to access related content quickly and easily. However, too many links can make your writing difficult to read, so use links carefully.

Create a hyperlink for the title of the item you are linking to. Make the hyperlinked text part of your sentence.

If possible, include a verb that tells your reader what they will do when they click the hyperlink. Avoid embedding the link in an extra word like here.

Sometimes, text should not be hyperlinked. For example, when you want the reader to see the URL. For these cases you can print the link and use a hyperlink.

Example: To view your content open http://localhost:1313

Use second person point of view

Use second person to refer to your reader, and when writing user-oriented instructions. Second person uses, or implies, the pronoun you, and addresses your reader directly.

Using second person helps your reader to engage, and helps to avoid the use of passive voice, because your reader is the subject of the sentence.

If you have trouble starting a sentence, try starting with: You can

When writing user-oriented instructions or guidance, using you makes it clear that your reader, and not the item in discussion, is the agent who performs the action. In the following recommended example, it is clear that your reader is the agent using the flag to do the tracking, and that the flag is not doing the tracking automatically.

Give only required details

Use short, crisp sentences. Avoid storytelling and excessive background.

Be specific

Use numbers and provide examples when possible. Avoid general statements try to be as specific.

Be consistent

Be consistent because we like finding patterns and repetition. We understand content quicker if it is consistent. Make sure that you use the same words to describe the same things. For example, “This table/figure/example shows …” not depicts, lists, illustrates, defines. Use the same spelling, not “keywords” in one place and “key words” in another.

Expected skills of your target audience

Learning Paths are intended for software developers with differing experience levels (Introductory and advanced). The intended audience is expected to have some domain specific knowledge, examples of which are listed below: