diff options
| author | Alexander Ziaee <ziaee@FreeBSD.org> | 2026-11-15 10:38:47 +0000 |
|---|---|---|
| committer | Alexander Ziaee <ziaee@FreeBSD.org> | 2026-11-15 10:38:51 +0000 |
| commit | 8fad59f91dde7b4148ad5d5b00f74d8827bc8620 (patch) | |
| tree | d376b5438ba6154dcd50ef0a1f5feda53dd7be6f | |
| parent | 38a625a646ad4600a719a83b63c3918936f3db45 (diff) | |
FDP/writing style: Headings are in title case
In the FreeBSD documentation project, headings are title case following
older American publishing tradition. Google and Microsoft style guides
have switched to sentence case, but I for one like our old world style
and the quality it usually implies, and want to carry that torch.
There are different style houses have subtle nuances on what constitutes
a "small word", and I do not think there is anything to be gained from
doing a whole bikeshed on which one to follow and then trying to get all
the docs to use that consistently. For now, fix this consistently on the
writing style page without adding a new rule.
PR: 296223
Reviewed by: carlavilla
Differential Revision: https://reviews.freebsd.org/D61592
| -rw-r--r-- | documentation/content/en/books/fdp-primer/writing-style/_index.adoc | 9 |
1 files changed, 4 insertions, 5 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 ee098c5a1f..9fda7ffe61 100644 --- a/documentation/content/en/books/fdp-primer/writing-style/_index.adoc +++ b/documentation/content/en/books/fdp-primer/writing-style/_index.adoc @@ -107,7 +107,7 @@ One approach is to have an introduction, then a "quick start" section that descr 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:: +Use American English spelling:: There are several variants of English, with different spellings for the same word. Where spellings differ, use the American English variant. "color", not "colour", "rationalize", not "rationalise", and so on. @@ -119,7 +119,6 @@ The other documents such as books, web site, manual pages, etc. must use America ==== Do not use contractions:: -Do not use contractions. Always spell the phrase out in full. "Don't use contractions" is wrong. + @@ -168,7 +167,7 @@ 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. @@ -353,7 +352,7 @@ $ pkg install vale .... [[writing-style-using-vale-commandline]] -==== Using Vale on the command line +==== Using Vale on the Command Line Assuming that the `doc` repository was cloned into [.filename]#~/doc# the following commands are required to run: @@ -370,7 +369,7 @@ A better way to run the application is on specific folders or files rather than ====== [[writing-style-using-vale-editors]] -==== Using Vale in 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]. |
