Differences

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

--- style_guidelines [2021/09/22 03:06] – [Text Content Guidelines] hogwild
+++ style_guidelines [2023/07/16 18:10] (current) – [Layout/Formatting Guidelines] -add that variables should be italicized hogwild
@@ 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" on the [[https://www.linksysinfo.org/index.php?forums/tomato-firmware.33/|FreshTomato Forum]], 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.
+  * Some wiki readers are not fluent in English. Please, choose your words carefully. \\   \\
-  * For example, no one unfamiliar with Linux/Unix will know that "wl" denotes a wireless interface.
+  * Avoid abbreviations that aren't standard across the industry or in common English.   \\ For example, anyone unfamiliar with Linux/Unix will not know that "wl" indicates a wireless interface. If it's not standard across the industry, explain it. Using "LAN", for example, is okay. It's common terminology. \\ \\
-  * On the other hand, Wi-Fi is a standard term across computing, and society in general, and is therefore okay to use.
+  * Avoid the word "Note". It's overused and rarely appropriate. If the content isn't a critical warning, consider putting it in the <WikiPageName Notes> section at the bottom of the page. \\ \\
-  * Avoid non-standard abbreivations/short forms. For example, don't use "FT" for FreshTomato. Using LAN is okay, as it's commonly known.
+  * Avoid underlining. It's obsolete and inappropriate. Research shows it makes things harder to read. \\ \\
-  * Avoid use of the word "Note". It's used way too often. It should be used only when something is unusually important. Using it constantly is like using underlining constantly, it causes the text to 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.
+  * Please view other pages to see which types of text are capitalized and which are written in lower case. \\ \\
-  * Avoid using underlining. Underlining is considered obsolete. It's a throwback from typewriter times.
+  * Please use a spell checker. Firefox's spellchecker works well for this. \\ \\
-  * Please keep with the standard formatting conventions being used for type, such as (sub)Heading levels and body text.
+  * When referring to FreshTomato menus, please indicate as: //Menu///Submenu// . //  For example: //"Administration///Admin access"// . //\\ \\
-  * Standard formatting conventions include which words are capitalized and which use lower case.
+  * Avoid using quotation marks, except around filenames. They're almost never appropriate. If you're unsure, don't use them. \\ \\
-  * Please use a spell checker. Firefox's browser-based spellchecker works well for this purpose.
+  * Please surround filenames with double quotation marks. For example, "wg0.conf".  \\ \\
-  * When referring to menus, please write the text as //Menu/Submenu . //For example, //Administration/Admin access .//
+  * Please use rounded brackets () . Square brackets are generally not appropriate here. \\ \\
-  * 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 have special purposes which don't apply here.
 ===== Layout/Formatting Guidelines =====
-Following guidelines makes the wiki easier to understand, and easier and more pleasant to read.
+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.
+The FreshTomato wiki uses [[https://www.dokuwiki.org/dokuwiki|dokuwiki]] as its underlying software. It uses [[https://prosemirror.net/|ProseMirror]] as its editor.
-  * 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.
+Focus on content.  Not everyone uses the same size monitor or resolution. Some people use a mobile device to access the wiki. \\ Different browsers and accessibility also affect how formatting appears (for example, with line breaks).
-  * {{:pasted:20210921-184547.png}}
-  * 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.
+  * Add a meaningful title to each wiki page. Format it with the Heading1 format. \\ \\
-  * Command strings should be emboldened, like this: **ssh root@192.168.10.1**
+  * Subheadings use the Heading2 format. \\ \\
-  * Variables should be italicized.
+  * Subheadings below that use the Heading3 format. \\ \\
+  * Indicate web interface menu paths using the name of the menu, unless there is another menu with a similar name.
+    * For example, you can refer to the Admin Access menu. However...
+    * You should add a "/" and top node when referring to the ///Bandwidth///[[bwm-realtime|Real-Time]] menu.\\ This will help prevent it from being confused with the //IP Traffic///[[ipt-realtime|Real-Time]] menu.\\ \\
+  * Always use the "Tomato" theme when taking screenshots. This is set in the [[admin-access|Admin Access]] menu.
+\\ {{:pasted:20210921-184547.png|A screenshot in the Standard Tomato theme}}  \\   \\
+  * Avoid quotation marks. In the context of this wiki, they should be used only:
+    * When slang is used.
+    * When expressing, something precise separate from the text body, such as a filesystem path. \\ \\
+  * Avoid underlining. It's been 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 for notes. \\ \\
+  * 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 to distinguish them from the main text//. \\ \\
+  * Process/Module names should be italicized to distinguish them from the main text. \\ \\
+  * Avoid using dividing lines. They are mostly obsolete. Better spacing, and modern formatting methods work better. \\ \\

FreshTomato Wiki

User Tools

Site Tools

Differences

Page Tools