Differences

This shows you the differences between two versions of the page.

--- style_guidelines [2021/09/22 03:18] – [Text Content Guidelines] hogwild
+++ style_guidelines [2022/03/13 01:06] – :) djk44883
@@ Line 1: / Line 1: @@
-====== Style Guidelines (Wiki Edits) ======
+====== Style Guidelines (Wiki Editing) ======
 ===== 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.
+To be able to edit the Wiki, you will need to get new user credentials. To request access, please send a personal message to user "rs232", including your email address and preferred username.
 ===== Text Content Guidelines =====
-  * Avoid using specialized abbreviations that aren't standard \\ across the tech industry or in common English unless necessary.\\ For example, no one unfamiliar with Linux/Unix will know that "wl" \\ indicates a wireless interface. \\ However, Wi-Fi is a standard term across computing, and society \\ in general, and is therefore safe to use.
+  * There may be wiki readers not fluent in English. Please choose your words carefully.
-  * 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 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. WiFi, however, is a standard term across computing, and society in general, and is safer to use.
-  * Avoid using of 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 will soon decide on a standard for formatting notes, so there will be no need for this an.
+  * Avoid non-standard abbreviations/short forms. For example, don't use "FT" for FreshTomato. Using LAN is okay, as it's common terminology.
-  * Avoid using underlining. Underlining is considered obsolete. It's a throwback from typewriter times.
+  * 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 guidelines/standards for writing and formatting notes.
-  * Please keep with the standard formatting conventions being used for type, such as (sub)Heading levels and body text.
+  * Avoid using underlining. It's obsolete and inappropriate. Research shows it also makes things harder to read.
-  * Standard formatting conventions include which words are capitalized and which use lower case.
+  * Please view other pages to see what text is capitalized and what is written in lower case (small letters).
-  * Please use a spell checker. Firefox's browser-based spellchecker works well for this purpose.
+  * Please use a spell checker. Firefox's spellchecker works well for this.
-  * When referring to menus, please write the text as //Menu/Submenu . //For example, //Administration/Admin access .//
+  * When referring to FreshTomato's menus, please indicate 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.
+  * Avoid using quotation marks. They're almost never appropriate. If you're not sure, don't use them.
-  * Please use rounded brackets () and not square brackets. Square brackets have special purposes which don't apply here.
+  * Please use rounded brackets () . Square brackets are generally not appropriate here.
 ===== Layout/Formatting Guidelines =====
-Following guidelines makes pages easier to understand, more pleasant to read, and eaiser on the brain and eyes.
+Following style guidelines makes pages easier to understand, more pleasant to read, and easier on the brain and eyes.
+Focus on content.  Not everyone will use the same size monitor or resolution. It's possible users may have mobile devices or various models of laptops to access the wiki. Users may click Toggle theme changing the entire appearance from what you see.  Different browsers and accessibility come into play as well.
   * Add a meaningful title for each wiki page, and format it with the Heading1 format.
-  * Indicate web interface menu paths like this: "navigate to //Administration/Admin Access//." (Use / to separate //italicized// menu nodes).
+  * Subheadings use the Heading2 format.
-  * Always use the standard Tomato theme when taking screenshots. \\ {{:pasted:20210921-184547.png}}
+  * Subheadings below that use the Heading3 format.
-  * 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.
+  * Indicate web interface menu paths like this: "//Administration/Admin Access//." (Use / to separate //italicized// menu nodes).
-  * Avoid underlining. It was considered obsolete since the 1980s.
+  * Always use the standard Tomato theme when taking screenshots. This is set in the [[admin-access|Admin Access]] menu.
-  * 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.
+\\ {{:pasted:20210921-184547.png|A screenshot in the Standard Tomato theme}}
+ \\
+ \\
+  * Avoid using quotation marks except where absolutely appropriate.
+  * They are rarely appropriate, and should only be used when quoting someone/ something directly, or when slang/colloquialisms are used.
+  * Avoid underlining. It has been considered obsolete since the 1980s. It makes text harder to read.
+  * Avoid using the word “NOTE”. There is a section titled "<Menu name> Notes" at the bottom of most pages.
+  * Unless they are in a code window, command strings should be set in the ''monospace'' font, or in a callout box.
+  * Variables should be italicized.
+  * Process/Module names should be italicized to set them off from the main text.
+  * Avoid using dividing lines. Better spacing, and other formatting methods work better.
+  * Avoid excessive unnecessary blank lines.  These just needlessly increases page length.
+  * If you've read this far you've noticed several points just repeat from one section to the next.  Been like this since the beginning, but this isn't as important as nit-picking and minor nonsense editing. any one notice?

FreshTomato Wiki

User Tools

Site Tools

Differences

Page Tools