Skip to content

Commit

Permalink
Update writing.adoc
Browse files Browse the repository at this point in the history
fixing the broken sentence

Signed-off-by: Kersten Richter <[email protected]>
  • Loading branch information
kersten1 committed Aug 27, 2024
1 parent bbed23a commit 567b82e
Showing 1 changed file with 5 additions and 24 deletions.
29 changes: 5 additions & 24 deletions src/writing.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
|===
Expand All @@ -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
Expand All @@ -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"]
|===
Expand All @@ -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.
Expand Down Expand Up @@ -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"]
|===
Expand Down

0 comments on commit 567b82e

Please sign in to comment.