aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlexander Ziaee <ziaee@FreeBSD.org>2026-11-15 10:38:47 +0000
committerAlexander Ziaee <ziaee@FreeBSD.org>2026-11-15 10:38:51 +0000
commit8fad59f91dde7b4148ad5d5b00f74d8827bc8620 (patch)
treed376b5438ba6154dcd50ef0a1f5feda53dd7be6f
parent38a625a646ad4600a719a83b63c3918936f3db45 (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.adoc9
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].