diff options
Diffstat (limited to 'documentation/content/en/books/fdp-primer/writing-style/_index.adoc')
| -rw-r--r-- | documentation/content/en/books/fdp-primer/writing-style/_index.adoc | 168 |
1 files changed, 146 insertions, 22 deletions
diff --git a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc index ba17cdf890..965998b9eb 100644 --- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc @@ -1,23 +1,24 @@ --- -title: Chapter 11. Writing Style +title: Chapter 12. Writing Style prev: books/fdp-primer/manual-pages next: books/fdp-primer/editor-config description: Writing Style and some conventions used in the FreeBSD Documentation Project -tags: ["writing", "style", "tipos", "one sentence per line"] +tags: ["writing", "style", "typos", "one sentence per line"] showBookMenu: true weight: 12 -path: "/books/fdp-primer/" +params: + path: "/books/fdp-primer/writing-style/" --- [[writing-style]] = Writing Style :doctype: book :toc: macro -:toclevels: 1 +:toclevels: 2 :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 11 +:sectnumoffset: 12 :partnums: :source-highlighter: rouge :experimental: @@ -52,7 +53,8 @@ endif::[] Technical documentation can be improved by consistent use of several principles. Most of these can be classified into three goals: _be clear_, _be complete_, and _be concise_. -These goals can conflict with each other. Good writing consists of a balance between them. +These goals can conflict with each other. +Good writing consists of a balance between them. [[writing-style-be-clear]] === Be Clear @@ -79,8 +81,7 @@ A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like "but really it should never be done that way". Bad examples are worse than no examples. -Give good examples, because _even when warned not to use the example as shown_, -the reader will usually just use the example as shown. +Give good examples, because _even when warned not to use the example as shown_, the reader will usually just use the example as shown. Avoid _weasel words_ like "should", "might", "try", or "could". These words imply that the speaker is unsure of the facts, and create doubt in the reader. @@ -98,18 +99,14 @@ Put yourself in the reader's place, anticipate the questions they will ask, and [[writing-style-be-concise]] === Be Concise -While features should be documented completely, -sometimes there is so much information that the reader cannot easily find the specific detail needed. +While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed. The balance between being complete and being concise is a challenge. -One approach is to have an introduction, -then a "quick start" section that describes the most common situation, -followed by an in-depth reference section. +One approach is to have an introduction, then a "quick start" section that describes the most common situation, followed by an in-depth reference section. [[writing-style-guidelines]] == Guidelines -To promote consistency between the myriad authors of the FreeBSD documentation, -some guidelines have been drawn up for authors to follow. +To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow. Use American English Spelling:: There are several variants of English, with different spellings for the same word. @@ -118,9 +115,8 @@ Where spellings differ, use the American English variant. + [NOTE] ==== -The use of British English may be accepted in the case of a contributed article, -however the spelling must be consistent within the whole document. -The other documents such as books, web site, manual pages, etc. will have to use American English. +The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document. +The other documents such as books, web site, manual pages, etc. must use American English. ==== Do not use contractions:: @@ -159,13 +155,13 @@ Wrong: ... in the filename [.filename]#/etc/rc.local#... + Right: ... in [.filename]#/etc/rc.local#... + -Manual page references (the second example uses `citerefentry` with the man:csh[1] entity):. +Manual page references (the second example uses `man:[]` with the man:csh[1] entity): + Wrong: See `man csh` for more information. + Right: See man:csh[1]. -For more information about writing style, see http://www.bartleby.com/141/[Elements of Style], by William Strunk. +For more information about writing style, see http://www.bartleby.com/141/[Elements of Style] by William Strunk. [[writing-style-guide]] == Style Guide @@ -173,13 +169,13 @@ For more information about writing style, see http://www.bartleby.com/141/[Eleme To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions. [[one-sentence-per-line]] -== One sentence per line +=== One sentence per line Use Semantic Line Breaks in the documentation, a technique called "one sentence per line". The idea of this technique is to help the users to write and read documentation. To get more information about this technique read the link:https://sembr.org/[Semantic Line Breaks] page. -This is an example which don't use "one sentence per line". +This is an example which does not use "one sentence per line". .... All human beings are born free and equal in dignity and rights. They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood. @@ -252,3 +248,131 @@ If a character is not on this list, ask about it on the {freebsd-doc}. | <= |=== + +[[writing-style-linting-vale]] +== Linting with Vale + +To maintain clarity and consistency across all documentation and website pages, link:https://vale.sh[Vale] styles have been introduced in the documentation tree. +link:https://vale.sh[Vale] is a powerful linter for writing customized rules and can be used in multiple scenarios. +Currently link:https://vale.sh[Vale] can be used as a command line tool, for CI/CD pipelines, and integrated into an editor of choice. + +The following table describes the current rule names and their respective severity. + +[.informaltable] +[cols="1,1", frame="none", options="header"] +|=== +| Name +| Severity + +| FreeBSD.BrandTerms +| error + +| FreeBSD.ConsciousLanguage +| warning + +| FreeBSD.Contractions +| suggestion + +| FreeBSD.EOLSpacing +| warning + +| FreeBSD.Hang +| warning + +| FreeBSD.Hyphens +| warning + +| FreeBSD.Spacing +| error + +| FreeBSD.SuperfluousOptArgInLinks +| suggestion + +| Vale.Avoid +| error + +| Vale.Repetition +| error + +| Vale.Spelling +| error + +| Vale.Terms +| error + +|=== + +[[writing-style-linting-vale-rules]] +=== Current Vale Rules + +. FreeBSD.BrandTerms: According to the copyright rules of The FreeBSD Foundation, *freebsd* should be written as *FreeBSD*. +Similarly, every major vendor and company has specific rules on writing their brand names and trademarks. +Care should be taken to be respectful to the brand value of others and to take time to write PostgreSQL, Node.js, Let's Encrypt etc. +Missing brand names should be added to the [.filename]#.vale/styles/FreeBSD/BrandTerms.yml# in the `doc` repository. + +. FreeBSD.ConsciousLanguage: This rule proposes use of conscious language so that sensitive words pointing to the color, age, race, or sexual orientation of people are avoided where possible. + +. FreeBSD.Contractions: Contracted words should not be used. +This rule avoids all contractions and suggests full words. + +. FreeBSD.EOLSpacing: In most of the documents EOL spacing is present which is not the desirable situation. + +. FreeBSD.Hang: `Hang` is often used to mean that the application has stopped responding. +This rule proposes better wording. + +. FreeBSD.Hyphens: Often adverbs ending with 'ly' are added with a hyphen which is wrong. + +. FreeBSD.Spacing: Often double spaces are hard to catch with the naked eye and this is addressed here. + +. FreeBSD.SuperfluousOptArgInLinks: Suggest to empty square brackets in `link:` macros when the displayed text coincides with the URL. + +. Vale.Avoid: Enforces the *DO NOT USE* vocabulary terms for The FreeBSD Project. +If any word is found that should not be in the documentation, the word should be added to [.filename]#.vale/styles/Vocab/Terms/reject.txt# in the `doc` repository. +The list is empty at the moment. + +. Vale.Repetition: Same words are often typed twice when leaving the keyboard and rejoining the work again. +This rule finds repeated words and warns the users. + +. Vale.Spelling: At the moment there is a mix of en_US and en_GB spellings in the documentation and website. +Vale comes with an in built dictionary from which uses strictly en_US and do not accept the en_GB variant of any words. + +. Vale.Terms: Enforces the *PREFERRED* vocabulary terms for The FreeBSD Project. +At the moment the list of terms is empty and the FreeBSD specific terms will be added gradually. +If any word is found to be correct and not available in the dictionary the word should be added to the [.filename]#.vale/styles/Vocab/Terms/accept.txt# in the `doc` repository. + +More rules will be introduced in the upcoming days when and where required. + +[[writing-style-using-vale]] +=== Using Vale + +link:https://vale.sh[Vale] can be used from the command line and from within an editor or IDE. +package:textproc/vale[] can be installed as following: + +[source, shell] +.... +$ pkg install vale +.... + +[[writing-style-using-vale-commandline]] +==== Using Vale on the command line + +Assuming that the `doc` repository was cloned into [.filename]#~/doc# the following commands are required to run: + +[source, shell] +.... +% cd ~/doc +% vale . +.... + +[NOTE] +====== +link:https://vale.sh[Vale] is a CPU and memory intensive program due to the nature of the application and can take a while to show any output on the screen. +A better way to run the application is on specific folders or files rather than the entire `doc` repository as that is already done in the CI pipeline. +====== + +[[writing-style-using-vale-editors]] +==== Using Vale in editors + +link:https://vale.sh[Vale] works with major mainstream editors like package:editors/vim[], package:editors/emacs[], package:editors/vscode[]. +At the moment the necessary configuration for package:editors/vim[] is described in crossref:editor-config[editor-config-vim, Vim]. +A configuration for package:editors/emacs[] is being worked on. |