diff --git a/src/writing.adoc b/src/writing.adoc index cb702e8..bd26232 100644 --- a/src/writing.adoc +++ b/src/writing.adoc @@ -35,7 +35,7 @@ Exception: Use passive voice if active voice leads to an awkward construction. === Use simple and direct language -Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." +Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." Direct language is easier to translate. [cols="1,1"] |=== @@ -54,6 +54,8 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying === Address the reader as "you" +Using "we" in a sentence can be confusing, because the reader might not know whether they're part of the "we" that you're describing. Does it mean the RISC-V team, the RISC-V members, open source people, hardware people, or even everyone? + [cols="1,1"] |=== |Yes @@ -70,7 +72,7 @@ An exception to this rule is the rationale sections. === Avoid Latin phrases -Prefer English terms over Latin abbreviations. +Prefer English terms over Latin abbreviations. Latin terms can be difficult for translation because it adds an additional language to translate. [cols="1,1"] |=== @@ -84,27 +86,6 @@ Prefer English terms over Latin abbreviations. |i.e., |=== - -=== Avoid using "we" - -Using "we" in a sentence can be confusing, because the reader might not know -whether they're part of the "we" you're describing. - -[cols="1,1"] -|=== -|Yes -|No - -|Version 1.4 includes -|In version 1.4, we have added - -|RISC-V provides a new feature for -|We provide a new feature - -|This page teaches you how to create CSRs. -|In this page, we are going to learn about CSRs. -|=== - === Avoid jargon and idioms Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. @@ -148,7 +129,7 @@ considered new in a few months. === Avoid words that assume a specific level of understanding -Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel +Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel not up to the task. [cols="1,1"] |===