Site Tools


style_guidelines

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
style_guidelines [2022/03/13 01:06] – :) djk44883style_guidelines [2023/07/16 18:10] (current) – [Layout/Formatting Guidelines] -add that variables should be italicized hogwild
Line 3: Line 3:
 ===== Wiki Editing Rights ===== ===== 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 user "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 ===== ===== Text Content Guidelines =====
  
-  * There may be wiki readers not fluent in English. Please choose your words carefully. +  * Some wiki readers are not fluent in English. Pleasechoose 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. WiFi, however, is a standard term across computingand society in general, and is safer to use. +  * 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 industryexplain itUsing "LAN"for example, is okay. It's common terminology. \\ \\  
-  * Avoid non-standard abbreviations/short forms. For example, don't use "FT" for FreshTomato. Using LAN is okay, as it's common terminology. +  * Avoid the word "Note". It's overused and rarely appropriateIf the content isn't a critical warningconsider putting it in the <WikiPageName Notes> section at the bottom of the page\\ \\  
-  * Avoid using the word "Note". It's overused and should be used only when something is unusually importantUsing it constantly makes the text  lose its impactand makes it more jarring to read. We'll develop some guidelines/standards for writing and formatting notes+  * Avoid underlining. It's obsolete and inappropriate. Research shows it makes things harder to read. \\ \\  
-  * Avoid using underlining. It's obsolete and inappropriate. Research shows it also makes things harder to read. +  * Please view other pages to see which types of text are capitalized and which are written in 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 spellchecker works well for this. \\ \\  
-  * Please use a spell checker. Firefox's spellchecker works well for this. +  * When referring to FreshTomato menus, please indicate as: //Menu///Submenu// . //  For example//"Administration///Admin access"// . //\\ \\  
-  * When referring to FreshTomato'menus, please indicate as: //Menu/Submenu . //  For example//Administration/Admin access .// +  * Avoid using quotation marks, except around filenames. They're almost never appropriate. If you're unsure, don't use them. \\ \\   
-  * Avoid using quotation marks. They're almost never appropriate. If you're not sure, don't use them. +  * Please surround filenames with double quotation marks. For example, "wg0.conf" \\ \\  
-  * Please use rounded brackets () . Square brackets are generally not appropriate here.+  * Please use rounded brackets () . Square brackets are generally not appropriate here. \\ \\
  
  
Line 24: Line 24:
 Following style guidelines makes pages easier to understand, more pleasant to read, and easier 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 resolutionIt's possible users may have mobile devices or various models of laptops to access the wikiUsers may click Toggle theme changing the entire appearance from what you see Different browsers and accessibility come into play as well+The FreshTomato wiki uses [[https://www.dokuwiki.org/dokuwiki|dokuwiki]] as its underlying softwareIt uses [[https://prosemirror.net/|ProseMirror]] as its editor.
  
-  * Add a meaningful title for each wiki page, and format it with the Heading1 format. +Focus on content.  Not everyone uses the same size monitor or resolutionSome people use a mobile device to access the wiki\\ Different browsers and accessibility also affect how formatting appears (for example, with line breaks).
-  * Subheadings use the Heading2 format. +
-  * Subheadings below that use the Heading3 format. +
-  * Indicate web interface menu paths like this: "//Administration/Admin Access//." (Use / to separate //italicized// menu nodes)+
-  * Always use the standard 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 using quotation marks except where absolutely appropriate.  +  * Add a meaningful title to each wiki page. Format it with the Heading1 format. \\ \\  
-  * They are rarely appropriateand should only be used when quoting someonesomething directly, or when slang/colloquialisms are used. +  * Subheadings use the Heading2 format. \\ \\  
-  * Avoid underlining. It has been considered obsolete since the 1980s. It makes text harder to read. +  * Subheadings below that use the Heading3 format\\ \\  
-  * Avoid using the word “NOTE”. There is a section titled "<Menu name> Notes" at the bottom of most pages. +  * Indicate web interface menu paths using the name of the menuunless there is another menu with a similar name.  
-  * Unless they are in a code window, command strings should be set in the ''monospace'' font, or in a callout box. +    * For example, you can refer to the Admin Access menu. However... 
-  * Variables should be italicized. +    * 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.\\ \\ 
-  * Process/Module names should be italicized to set them off from the main text.  +  * Always use the "Tomato" theme when taking screenshots. This is set in the [[admin-access|Admin Access]] menu. 
-  * Avoid using dividing lines. Better spacing, and other formatting methods work better. + 
-  * Avoid excessive unnecessary blank lines.  These just needlessly increases page length. +\\ {{:pasted:20210921-184547.png|A screenshot in the Standard Tomato theme}}  \\   \\ 
-  * 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?+ 
 +  * 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'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. \\ \\ 
  
style_guidelines.1647133598.txt.gz · Last modified: 2022/03/13 01:06 by djk44883