From 462a23ba388b3a24b0776dab2ff54452c180974d Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Wed, 31 Jul 2024 21:00:07 -0500 Subject: [PATCH] bit of a reorg --- src/docs-dev-guide.adoc | 8 +- src/style-guidelines.adoc | 215 +++++++---------------------------- src/tables_symbols_math.adoc | 31 +---- src/writing.adoc | 181 +++++++++++++++++++++++++---- 4 files changed, 205 insertions(+), 230 deletions(-) diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc index f1534ec..337937f 100755 --- a/src/docs-dev-guide.adoc +++ b/src/docs-dev-guide.adoc @@ -58,7 +58,7 @@ This document is released under a Creative Commons Attribution 4.0 International //the colophon allows for a section after the preamble that is part of the frontmatter and therefore not assigned a page number. include::colophon.adoc[] -//While some documents need several levels of introductory material, other documents only need a brief introduction. You can choose to have either colophon or an overview, or to have both. +//While some documents need several levels of introductory material, other documents need only a brief introduction. You can choose to have either colophon or an overview, or to have both. include::intro.adoc[] include::authoring.adoc[] @@ -73,13 +73,13 @@ include::index_bib.adoc[] include::graphics.adoc[] -include::writing.adoc[] - include::style-guidelines.adoc[] +include::writing.adoc[] + include::linting.adoc[] -//please note that the index must precede the bibliography for both to work within the same book. +//Note that the index must precede the bibliography for both to work within the same book. include::index.adoc[] include::bibliography.adoc[] diff --git a/src/style-guidelines.adoc b/src/style-guidelines.adoc index 8e88b55..34194ae 100644 --- a/src/style-guidelines.adoc +++ b/src/style-guidelines.adoc @@ -1,204 +1,71 @@ == RISC-V Style guidelines [style-guidelines] +Whether you are creating a new extention or even a stand alone doc for RISC-V, follow these style guidelines to improve readability. + +[[basic-rules]] +=== Basic formatting + Follow these basic formatting guidelines. * Use _italic_ for new terms. * Use `monospace` for filenames, directories, and paths. -* Put punctuation outside of quotes, unless you are quoting someone directly. * Use `monospace` for inline code and commands. * Use *`monospace bold`* for hex numbers. Hex numbers start with `0x`. * Use *`monospace bold`* for binary numbers. Binary numbers start with `0b`. * Use *`monospace bold`* for any literals. -* Any number range, use regular font +* Any number range, use regular font. +* Put punctuation outside of quotes, unless you are quoting someone directly. -See the next section for rules about referring to a CSR. +.Formatting guidelines for names +* Instructions are lowercase (`ld`, `c`.`lw`) +* Extensions are Capitialized (`A`, `C`, `Zicsr`) +* CSR short names are lowercase (`misa`). +* All of these names are in monospace. [[csr-rules]] -=== Referring to CSRs or registers +=== CSR formatting Use the following guidelines when you document a CSR: -* CSR must always be capitalized. +* The acronym CSR must always be capitalized. * When plural, lowercase the `s`. CSRs. -* Register is capitalized in title, but lowercase in text. "Supervisor Status (`sstatus`) Register”. But “The `sstatus` register…” +* The word `Register` is capitalized in title, but lowercase in text. "Supervisor Status (`sstatus`) Register”. But “The `sstatus` register…” * When in doubt, use "CSR" to indicate the type of register. You can then intermingle CSR and register in the text. So "The `misa` CSR is used to...." And then later in the paragraph, you can use "register". As in, "This register also does this other thing." -* In a title, the format is “Long name (`short name`) Register. All other references in that section can use the short name, but it must be in tics. So "Supervisor Status (`sstatus`) Register”. The rest of the references to that register can be "the `sstatus` CSR". * Avoid starting a sentence with a CSR name. -* As a general rule, whenever you use a term in tics, it should be followed by what the thing is to help with translation. So avoid statements like this: “`misa` also helps distinguish different variants of a design.” And instead use this: “The `misa` CSR also helps distinguish different variants of a design.” -* Fields for registers are formatted in this style: `register`.FIELD. For example, `sstatus`.SPP - -=== General best practices - - -This section contains suggested best practices for clear, concise, and consistent content. - -==== Use present tense - - -[cols="1,1"] -|=== -|Yes -|No - -|Cache-management operation instructions perform operations on copies of data in the memory hierarchy. -|Cache-management operation instructions will perform operations on copies of data in the memory hierarchy. -|=== - -Exception: Use future or past tense if it is required to convey the correct -meaning. - -==== Use active voice - -[cols="1,1"] -|=== -|Yes -|No - -|You can use the RVWMO memory model... -|The RVWMO memory model can be used... - -|The RVWMO memory model enables architects -|Architects are enabled by the RVWMO memory model. -|=== - -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." - -[cols="1,1"] -|=== -|Yes -|No - -|To build a chip, ... -|In order to build a chip, ... - -|See the Hypervisor extension. -|Please see the Hypervisor extension. - -|View the register. -|With this next command, we'll view the register. -|=== - -==== Address the reader as "you" - -[cols="1,1"] -|=== -|Yes -|No - -|You can use the `misa` CSR ... -|We'll use the `misa` CSR ... - -|In the preceding output, you can see... -|In the preceding output, we can see ... -|=== - -==== Avoid Latin phrases - -Prefer English terms over Latin abbreviations. - -[cols="1,1"] -|=== -|Yes -|No - -|For example, ... -|e.g., ... - -|That is, ... -|i.e., ... -|=== - - -=== Patterns to avoid - -==== 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. -|=== - -An exception for using "we" is the rationale sections. - - -==== Avoid jargon and idioms - -Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. - -[cols="1,1"] -|=== -|Yes -|No - -|Internally, ... -|Under the hood, ... - -|Stop trying. -|Chutar o pau-da-barraca (which translates to "kicking away the tent pole") -|=== - -==== Avoid statements about the future - -Avoid making promises or giving hints about the future. If you need to talk about -an alpha feature, put the text under a heading that identifies it as alpha -information. - -An exception to this rule is documentation about announced deprecations targeting removal in future versions. - -==== Avoid statements that will soon be out of date - -Avoid words like "currently" and "new." A feature that is new today might not be -considered new in a few months. - -[cols="1,1"] -|=== -|Do -|Don't +* In a title, the format is “Long name (`short name`) Register. All other references in that section can use the short name, but it must be in monospace. So "Supervisor Status (`sstatus`) Register”. The rest of the references to that register can be "the `sstatus` CSR". +* The short name is always lower case and monospace: `sstatus`. +* As a general rule, whenever you use a term in tics, it should be followed by what the thing is to help with translation. So avoid statements similar to this one: “`misa` also helps distinguish different variants of a design.” And instead use this one: “The `misa` CSR also helps distinguish different variants of a design.” +* Fields for registers are formatted in this style: `register`.FIELD. For example, `sstatus`.SPP. -|In version 1.4, ... -|In the current version, ... +[[naming-rules]] -|The pointer masking extension provides ... -|The new pointer masking extension provides ... -|=== +[[table-rules]] +=== Table formatting -==== Avoid words that assume a specific level of understanding +Follow these formatting rules when you create a table. -Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel +* Align tables to center with the options `float="center"` and `align="center"`. +* Use table header coding to indicate a header. Don't use a different font, color, or any background indication. +* Sort rows in either a logical order or by alphabetizing the rows and columns. +* If your table is long or complicated, consider creating multiple tables. Remember that tables can be hard for screen readers to parse. If your table is complex, be sure that the contents are described in the text. +* Use table captions to describe your table contents. Captions appear after the table and are controlled by the theme. +* If you use footnotes in your table, make sure they appear immediately after the table. -[cols="1,1"] -|=== -|Do -|Don't +==== Column header formatting -|Include one command in ... -|Include just one command in ... +Follow these column header rules. -|Run the command ... -|Simply run the command ... +* Use sentence case. +* Write concise headings and omit articles (a, an, the). +* Don't end with punctuation, including a period, an ellipsis, or a colon. +* Use table headings for the first column and the first row only. -|You can remove ... -|You can easily remove ... +==== Punctuation in tables -|These steps ... -|These simple steps ... -|=== +Follow these punctuation rules for tables. +* If all cells in a table column are complete sentences, then end each cell with a period. +* If all cells in a table column are sentence fragments, then do not use a period to end each cell. +* If cells in a table column contain a mixture of complete and fragmented sentences, then first try to make them all parallel - either all complete sentences or all sentence fragments. However, if this approach is impractical, then punctuate each cell independently, and punctuate appropriate for that individual cell. +- Do not end column headers with punctuation, including a period, an ellipsis, or a colon. diff --git a/src/tables_symbols_math.adoc b/src/tables_symbols_math.adoc index 2b35c42..2314acf 100644 --- a/src/tables_symbols_math.adoc +++ b/src/tables_symbols_math.adoc @@ -10,37 +10,8 @@ Follow these general rules when you create a table. * Use introductory sentences for your table. For example, "The following table contains the options for the CSR." You can use either a period or a colon for your introductory sentence. * Do not refer to the "table above" or the "below table". Use words such as "The following table" or "The preceeding table". -==== Table formatting +For table formatting rules, see <>. -Follow these formatting rules when you create a table. - -* Align tables to center with the options `float="center"` and `align="center"`. -* Use table header coding to indicate a header. Don't use a different font, color, or any background indication. -* Sort rows in either a logical order or by alphabetizing the rows and columns. -* If your table is long or complicated, consider creating multiple tables. Remember that tables can be hard for screen readers to parse. If your table is complex, be sure that the contents are described in the text. -* Use table captions to describe your table contents. Captions appear after the table and are controlled by the theme. -* If you use footnotes in your table, make sure they appear immediately after the table. - - - -==== Column header formatting - -Follow these column header rules. - -* Use sentence case. -* Write concise headings and omit articles (a, an, the). -* Don't end with punctuation, including a period, an ellipsis, or a colon. -* Use table headings for the first column and the first row only. - - -==== Punctuation in tables - -Follow these punctuation rules for tables. - -* If all cells in a table column are complete sentences, then end each cell with a period. -* If all cells in a table column are sentence fragments, then do not use a period to end each cell. -* If cells in a table column contain a mixture of complete and fragmented sentences, then first try to make them all parallel - either all complete sentences or all sentence fragments. However, if this approach is impractical, then punctuate each cell independently, and punctuate appropriate for that individual cell. -- Do not end column headers with punctuation, including a period, an ellipsis, or a colon. [WARNING] ==== diff --git a/src/writing.adoc b/src/writing.adoc index 19e2a21..5ff2b8d 100644 --- a/src/writing.adoc +++ b/src/writing.adoc @@ -1,41 +1,178 @@ [[writing-simple]] -== Writing tips +== Best practices -Follow these tips to write your documents well. +This section contains suggested best practices for clear, concise, and consistent content. -[[simple-concise]] -=== Write simply and concisely +=== Use present tense -Keep your writing as simple as possible. +[cols="1,1"] +|=== +|Yes +|No -* Use as few words as possible without sounding too formal or too casual. -* Shorten or simplify long sentences or else break them into separate sentences. -* Use lists to make the content more scannable. +|Cache-management operation instructions perform operations on copies of data in the memory hierarchy. +|Cache-management operation instructions will perform operations on copies of data in the memory hierarchy. +|=== -[[international-audience]] -=== Write for an international audience +Exception: Use future or past tense if it is required to convey the correct +meaning. -When you write, keep your international audience in mind. +=== Use active voice -* Use concepts consistently. Check the glossary for common terms and definitions. -* Avoid words that end in "ing". Words that end in "ing" can be a verb, adjective, or noun. Rewriting your sentence to avoid "ing" is best. So Rewrite your sentence to avoid "ing". +[cols="1,1"] +|=== +|Yes +|No -[[accessibility]] -=== Write for accessibility +|You can use the RVWMO memory model... +|The RVWMO memory model can be used... -Imagine how your doc sounds with a screen reader. Are your visual elements described? Do your tables make sense? +|The RVWMO memory model enables architects +|Architects are enabled by the RVWMO memory model. +|=== -[[active-voice]] -=== Write in the active voice +Exception: Use passive voice if active voice leads to an awkward construction. -Use the active voice as much as possible. +=== Use simple and direct language -When writing for highly technical audiences, strictly adhering to the use of active voice can result in convoluted sentences. As a result, while attempting to use active voice can result in improved clarity, contributors can choose to make use of passive voice. That said, we still encourage RISC-V contributors make use of active voice as much as possible. +Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." + +[cols="1,1"] +|=== +|Yes +|No + +|To build a chip, ... +|In order to build a chip, ... + +|See the Hypervisor extension. +|Please see the Hypervisor extension. + +|View the register. +|With this next command, we'll view the register. +|=== + +=== Address the reader as "you" + +[cols="1,1"] +|=== +|Yes +|No + +|You can use the `misa` CSR ... +|We'll use the `misa` CSR ... + +|In the preceding output, you can see... +|In the preceding output, we can see ... +|=== + +=== Avoid Latin phrases + +Prefer English terms over Latin abbreviations. + +[cols="1,1"] +|=== +|Yes +|No + +|For example, ... +|e.g., ... + +|That is, ... +|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. +|=== + +An exception for using "we" is the rationale sections. + + +=== Avoid jargon and idioms + +Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. + +[cols="1,1"] +|=== +|Yes +|No + +|Internally, ... +|Under the hood, ... + +|Stop trying. +|Chutar o pau-da-barraca (which translates to "kicking away the tent pole") +|=== + +=== Avoid statements about the future + +Avoid making promises or giving hints about the future. If you need to talk about +an alpha feature, put the text under a heading that identifies it as alpha +information. + +An exception to this rule is documentation about announced deprecations targeting removal in future versions. + +=== Avoid statements that will soon be out of date + +Avoid words like "currently" and "new." A feature that is new today might not be +considered new in a few months. + +[cols="1,1"] +|=== +|Do +|Don't + +|In version 1.4, ... +|In the current version, ... + +|The pointer masking extension provides ... +|The new pointer masking extension provides ... +|=== + +=== 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 + +[cols="1,1"] +|=== +|Do +|Don't + +|Include one command in ... +|Include just one command in ... + +|Run the command ... +|Simply run the command ... + +|You can remove ... +|You can easily remove ... + +|These steps ... +|These simple steps ... +|=== [[style-guidelines]] -=== Develop style guidelines only as needed +=== Other style guidelines -I have a list of existing guides that we can use as a starting point. These are likely the most pertinent existing style guidelines that were created for addressing the needs of highly technical audiences as opposed to consumer end user audiences: +Other style guidelines for reference: * https://www.writethedocs.org/guide/writing/style-guides/[Write the Docs style guide] * https://developers.google.com/style[Google's developer docs style guide]