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 [2021/09/22 02:00] hogwildstyle_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 +===== Wiki Editing Rights ===== 
-  To gain rights 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. + 
-  * \\ Add meaningful document title using Heading1 format+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. 
-  * \\ Indicate menu paths using notation like this: "navigate to //Administration/Admin Access//." [use / to separate //italicised// menu nodes]. + 
-  * \\ Use the standard Tomato theme for screenshots. //Administration/Admin Access//: + 
-  * \\ {{:pasted:20210921-184547.png}} +===== Text Content Guidelines ===== 
-  \\ Avoid using quotation marks where possible+ 
-  * \\ Avoid underlining. +  * Some wiki readers are not fluent in English. Please, choose your words carefully. \\   \\  
-  * \\ Avoid using “NOTE”. +  * 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 wireless interfaceIf it's not standard across the industry, explain it. Using "LAN", for example, is okay. It's common terminology. \\ \\  
-  * \\ Command strings should be emboldened: **ssh root@192.168.10.1**+  * 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 underlining. It's obsolete and inappropriate. Research shows it 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 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"// . //\\ \\  
 +  * Avoid using quotation marks, except around filenames. They're almost never appropriate. If you're unsure, 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. \\ \\ 
 + 
 + 
 +===== Layout/Formatting Guidelines ===== 
 + 
 +Following style guidelines makes pages easier to understand, more pleasant to read, and easier on the brain and eyes. 
 + 
 +The FreshTomato wiki uses [[https://www.dokuwiki.org/dokuwiki|dokuwiki]] as its underlying software. It uses [[https://prosemirror.net/|ProseMirror]as its editor. 
 + 
 +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). 
 + 
 + \\ 
 + 
 +  * Add a meaningful title to each wiki page. Format it with the Heading1 format. \\ \\  
 +  * Subheadings use the Heading2 format\\ \\  
 +  * 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 linesThey are mostly obsoleteBetter spacing, and modern formatting methods work better\\ \\
  
  
style_guidelines.txt · Last modified: 2023/07/16 18:10 by hogwild