BSDwiki/ Style Guide

It is important that the final document is consistent with formatting and general style. This guide shares some requirements and suggestions to help.

When editing please include at least a brief comment about your changes for the commit log.

Text Formatting

  • The document editing is done using Markdown syntax with a few extensions:

  • (((three parentheses))) will be used for indexing entries for the book's Index. For example:

    (((Syslog, reloading)))

  • Another extension for preformatted code or examples that use a fixed font is to prefix the line with two double-quotes (\"\"):

""drwxr-xr-x 4 reed reed 512 Oct 10 12:59 var

This is because the back-ticks notation does not allow Markdown formatting to be converted.

  • If you need real backticks within this custom preformatted block, then use HTML entity: ` TODO: check printed output
  • Do not use superfluous highlighting. Only use _italics_ or **bold** very rarely (if any).
  • Sometimes special characters like underscore (_) may need to be escaped with a slash (\).
  • Manually using LaTeX should not be needed.
  • Be careful with formatting as the PDF format for the printed book is generated from this content.
  • To include less-than (<) or greater-than (>) characters just put backticks around it or use HTML entities.

Length

  • Book length at book size will be around 200 to 250 pages. The book's objective is not to be a large encyclopaedic reference but a quick learning guide. (At initial import, the book was around 90 pages.)

  • Section lengths vary by topic, but with description and example(s) from a half (printed) page to three pages. If a topic becomes longer than three pages, split it up. (Note: at initial import there were 104 sections.)

Cross-references

Cross-references are handled for the printed book for referring to top-level sections as highlighted with two pound signs (##). A ## top-level section ## becomes a label. Also a label is automatically made that matches the individual wiki page name (minus the .html). Then to point to it just use two brackets [[Name_of_section]], for example:

See section Determine which process are consuming the most CPU for more details about ...

Note that sub-sections aren't automatically handled because we have multiple of these headers with identical naming.

Note that some special characters have been remapped for filenames. See below ...

File Naming

  • __39__ in the filename is a single quote
  • __40__ is a left parenthesis
  • __41__ is a right parenthesis
  • __44__ is a comma
  • a dash-dash (--) is replacement for a slash (in a filename)

General Notes

  1. Spell out asterisk and backslash and other characters as appropriate, like "using an asterisk (*) in the ...".
  2. "it__'__s" means "it is"; the possessive pronoun "its" does not have a single-quote (just like his or hers).
  3. Opinions should not be included just facts. Use comments or a sub-discussion page for discussion. If an option is really needed in book, attempt to back up all the opinions with solid fact, attribution or other references.
  4. Please do a spell check. For the main book, please use American English.
  5. Search for sentences that begin with "There are ..." (or "This is ...") and consider rewording them. (In other words, convert from passive voice to active voice.) For example, maybe start the sentence with a rewording from the end of the original sentence, add some action verb and then complete the sentence.
  6. Search for the word "that" -- does your sentence sound good without it?
  7. Use words for "zero" through "ten" (even "eleven" and "twelve" if you prefer) as appropriate.
  8. Don't have gender bias. Don't use "him" or "he".

Writing Suggestions

  1. Read your article out-loud -- does it sound natural?
  2. Teach the reader -- make sure your section is educational and something that the reader can learn from.
  3. If you have writer's block, try writing a letter to a friend teaching about the concept, describing it, and showing a few examples and explaining the examples. Then use that letter as the basis for your section.

To cover here in style guide

  • screenshots
  • tables
  • cross-reference other sections in book
  • reference man pages and outside docs, etc.
  • format for pathnames (and document in conventions)

maybe use fixed face for /path/to/file by using back ticks around it (TODO: escaping with backslashes is not working)

  • format for command output (and document in conventions)

maybe use indented block by indenting with four spaces or with a tab, for example:

this is indented with four spaces
this     is     more       output

Note that other markdown doesn't render within code blocks, so could use backticks as needed

  • differentiating commands from command output

maybe use bold for commands typed, for example

""$ echo foo ""foo

  • define choice like replace with your own value

maybe use italics, for example

""$ mail -u username

  • define consistent unix shell prompt

  • define how trademarks and capitalizations are to be handled