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
Next revisionBoth sides next revision
style_guidelines [2021/09/22 02:00] hogwildstyle_guidelines [2023/06/11 18:09] – [Layout/Formatting Guidelines] -condense 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 a 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 a wireless interface. If 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. We are developing guidelines/standards for writing and formatting notes. \\ \\  
 +  * Avoid underlining. It's obsolete and inappropriate. Also, 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. They're almost never appropriate. If you're unsure, don't use them. \\ \\  
 +  * 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 "Tomatotheme 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. \\ \\  
 +  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