Site Tools


style_guidelines

This is an old revision of the document!


Style Guidelines (Wiki Edits)

Wiki Editing Rights

To be able to edit the Wiki, you will need to get new user credentials. To request access, please send a personal message to @rs232, including your email address and preferred username.

Text Content Guidelines

  • For Many wiki readers, English is their second language. Choose your words carefully.
  • Avoid using specialized abbreviations that aren't standard
    across the technology industry or in common English.
    For example, anyone unfamiliar with Linux/Unix will not know that “wl”
    indicates a wireless interface. Explain it, or use it only where relevant.
    Wi-Fi, however, is a standard term across computing, and society
    in general, and is safer to use.
  • Avoid non-standard abbreviations/short forms. For example, don't use “FT”
    for FreshTomato. Using LAN is okay, as it's commonly known.
  • Avoid using the word “Note”. It's overused and should be used only when
    something is unusually important. Using it constantly makes the text
    lose its impact, and makes it more jarring to read. We'll develop
    some guiidelines/standards for writing and formatting notes.
  • Avoid using underlining. It's obsolete.
  • Please use the standard formatting conventions used for type, such as
    (sub)Heading levels and body text.
  • Please stay consistent with other pages in terms of which words are capitalized and which use lower case.
  • Please use a spell checker. Firefox's spellchecker works well for this purpose.
  • When referring to menus, please write the text as Menu/Submenu . For example, Administration/Admin access .
  • Avoid using quotation marks. Most of the time, they aren't appropriate. So if you're not sure, leave them out.
  • Please use rounded brackets () and not square brackets. Square brackets are generally not appropriate here.

Layout/Formatting Guidelines

Following style guidelines makes pages easier to understand, more pleasant to read, and easier on the brain and eyes.

  • Add a meaningful title for each wiki page, and format it with the Heading1 format.
  • Subheadings use the Heading2 format.
  • Subheadings below that use the Heading3 format.
  • Indicate web interface menu paths like this: “navigate to Administration/Admin Access.” (Use / to separate italicized menu nodes).
  • Always use the standard Tomato theme when taking screenshots.
  • Avoid using quotation marks except where absolutely appropriate. Quotation marks are rarely appropriate, and should generally only be used when quoting someone/ something directly, or when slang/colloquialisms are used.
  • Avoid underlining. It was considered obsolete since the 1980s.
  • Avoid using the word “NOTE”. We are considering adding a NOTES section at the bottom of each page formatted with Heading2.
  • Command strings should be emboldened, like this: ssh root@192.168.10.1
  • Variables should be italicized.
  • Avoid using dividing lines. Better spacing, and other formatting methods work better.
style_guidelines.1632281703.txt.gz · Last modified: 2021/09/22 04:35 by hogwild