FreshTomato Wiki

User Tools

Site Tools

Trace:
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 [2023/07/16 18:05] – [Text Content Guidelines] -add to surround filenames with quotation marks hogwildstyle_guidelines [2025/06/09 16:06] (current) – [Layout/Formatting Guidelines] -Remove "name" from image file syntax description 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" on the [[https://www.linksysinfo.org/index.php?forums/tomato-firmware.33/|FreshTomato Forum]], including your email address and preferred username. +To edit the Wiki, you'll need to get new user credentials. You can request access by sending a personal message to user "@rs232" on the [[https://www.linksysinfo.org/index.php?forums/tomato-firmware.33/|Tomato Forum]]. Make sure to include your email address and preferred username.
  
 ===== Text Content Guidelines ===== ===== Text Content Guidelines =====
  
-  * Some wiki readers are not fluent in English. Please, choose your words carefully. \\   \\  +  * Please **choose your words carefully**. Some wiki readers aren't fluent in English. \\ \\  
-  * 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. \\ \\  +  * Unless explaining complex concepts, please keep things **brief and concise. **\\ We aim to make the documentation simple and easy to read, even for beginners.  \\ Most **content is not meant to read like a reference manual**. Extra "precision" \\ can overwhelm readers. \\ \\  
-  * 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. \\ \\  +  * Add a **meaningful title** to every wiki page. Format it with the Heading1 format.  \\ \\ 
-  * Avoid underlining. It's obsolete and inappropriate. Research shows it makes things harder to read. \\ \\  +  * **Avoid abbreviations not standard across the industry** or in common English.   \\ For example, anyone unfamiliar with Linux/Unix may not know that "wl" indicates \\ a Broadcom wireless interface. If it's not industry standard terminology, explain it. \\ However, using "LAN", is fine. It's common industry terminology. \\ \\  
-  * Please view other pages to see which types of text are capitalized and which are written in lower case. \\ \\  +  * **Avoid **using **the word: "Note"**.  It's overused, and doesn't add meaning. \\ If the content isn't a critical warning, consider putting it in the\\ "Notes and Troubleshooting" section at the bottom of the page. \\ Otherwise, try bolding just a few of the most important words. \\ \\  
-  * Please use a spell checker. Firefox's spellchecker works well for this. \\ \\  +  * **Avoid underlining**. It's obsolete and makes things hard to read. \\ \\  
-  * When referring to FreshTomato menus, please indicate as: //Menu///Submenu// . //  For example: //"Administration///Admin access"// . //\\ \\  +  * Check other pages to see which kinds of text content are capitalized \\ and which are written in lower case. \\ \\  
-  * Avoid using quotation marks, except around filenames. They're almost never appropriate. If you're unsure, don't use them.  +  * Check spelling with your browser's spell checker. \\ \\  
-  * Please surround filenames with double quotation marks. For example, "wg0.conf".  \\ \\  +  * **When referring to FreshTomato web interface menus**: \\  
-  * Please use rounded brackets () . Square brackets are generally not appropriate here. \\ \\+    * If there's only one menu with that name, indicate menu paths using just \\ the name of the menu. For example, refer to the "Admin Access" menu. 
 +    * If there's more than one menu with a similar name, write it as:  \\ "/Menu/Submenu". \\ \\ For example: "/Bandwidth Monitoring/Real-Time". \\ \\ This differentiates it from the "/IP Traffic Monitoring/Real-Time" menu. \\ \\ 
 +  * **Avoid quotation marks**, except around filenames or numeric variables. \\ They're almost never appropriate. \\ \\   
 +  * **Use double quotation marks around filenames**. For example, "wg0.conf".  \\ \\  
 +  * **Use rounded brackets** "()" . Square brackets generally aren't appropriate and could\\ be confused with code snippets or markdown language.\\ \\
  
  
 ===== Layout/Formatting Guidelines ===== ===== Layout/Formatting Guidelines =====
  
-Following style guidelines makes pages easier to understand, more pleasant to read, and easier on the brain and eyes.+Following style guidelines makes content easier to read, and easier to understand. \\ It also reduces stress on the brain and eyes while reading. \\ \\
  
-The FreshTomato wiki uses [[https://www.dokuwiki.org/dokuwiki|dokuwiki]] as its underlying software. It uses [[https://prosemirror.net/|ProseMirror]] as its editor.+The wiki uses [[https://www.dokuwiki.org/dokuwiki|dokuwiki]] as its underlying software.
  
-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).+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 features also affect how formatting appears (such as line breaks). \\ \\  
 +  * **Subheadings use the Heading2** format, and subheadings below that, Heading3.\\ \\  
 +  * **When taking screenshots**, always use the "Tomato" theme (set in [[admin-access|Admin Access]]).\\  \\ {{:pasted:20210921-184547.png?497|A screenshot in the Standard Tomato theme}}  \\   \\  \\ In general, please use this syntax for naming screenshots files for upload:\\ ''"top node-bottom node-section name-release.png'' \\ \\ \\ For example, a screenshot of the Options section in the //Basic///DHCP Reservation menu \\ should be named "basic-dhcp reservation-options-2024.1". \\ \\  
 +  * For screenshots of just one or few settings options under one section, use syntax: \\ ''"top node-bottom node-option name to option name-release.png"''  \\ \\ \\ Example: "advanced-wireless-roaming assistant to fragmentation threshold-2024.1" \\  \\  
 +  * Please save screenshots in .png format. Lossy formats are blurry, \\ and may reveal your personal user data. \\ \\  
 +  * Please wrap bulleted text at less than 50% frame width. \\ It makes things much easier to read/follow. Shorter bulleted portions \\ should be wrapped even earlier for reading ease. \\ \\  
 +  * Screenshots in bitmap formats should be scaled/resized in even \\ multiples of their original size. Otherwise, they may appear blurry. \\ \\
  
-  * Add a meaningful title to each wiki page. Format it with the Heading1 format. \\ \\  +  * **Avoid quotation marks**. They should be used only: 
-  * Subheadings use the Heading2 format. \\ \\  +    - When slang is used. 
-  * Subheadings below that use the Heading3 format. \\ \\  +    - When expressing something precise, separate from body text, such as a filesystem path. \\ \\ 
-  * Indicate web interface menu paths using the name of the menu, unless there is another menu with a similar name.  +  * **Avoid underlining**. It's been obsolete since the 1980s and makes text harder to read. \\ \\  
-    * For example, you can refer to the Admin Access menu. However... +  * **Avoid using the word “Note”**. Put notes in the Notes section that exists \\ at the bottom of most pages.\\ \\  
-    * 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.\\ \\ +  * Except in a code window, **command strings should be set in the** ''monospace'' font, \\ or in a callout box.\\ \\  
-  * Always use the "Tomato" theme when taking screenshots. This is set in the [[admin-access|Admin Access]] menu.+  * Avoid dividing lines. They're obsolete and make text hard to read. \\ Better spacing and modern formatting methods work better.
  
-\\ {{: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 lines. They are mostly obsolete. Better spacing, and modern formatting methods work better. \\ \\+
  
  
style_guidelines.1689527142.txt.gz · Last modified: by hogwild

Page Tools

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki