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 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 like you are speaking, because that is too informal.
If you write in a clear, simple, and informal voice, your content will be easy to understand.
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. 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.
Passive voice (bad):
Use present tense because it is concrete. It emphasizes what the user can do now. And it uses fewer words.
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.
Too many ‘filler’ words:
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 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.
Use short, crisp sentences. Avoid storytelling and excessive background.
Use numbers and provide examples when possible. Avoid general statements try to be as specific.
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.
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:
|Software Development Areas
|Embedded and Microcontroller
|Understanding of programming languages such as C, C++ and assembly. Basic awareness of Linux OS, RTOSes. Fundamental knowledge of hardware and software architecture (not necessarily Arm)
|Server and Cloud
|Understanding of web services and Linux. Basic awareness of containerization and orchestration technologies such as Docker and Kubernetes. Proficient in programming languages such as Python and Java.
|Experience with software development on mobile platforms such as Android. Experience with mobile development and testing frameworks.
|Desktop and Laptop
|Experience with operating systems such as Windows and macOS. Experience with common development frameworks such as .NET and Electron. Proficient in programming languages such as C++, Java and Python.