Differences

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

--- style_guidelines [2022/02/03 16:58] – [Layout/Formatting Guidelines] hogwild
+++ style_guidelines [2025/03/09 15:31] (current) – [Layout/Formatting Guidelines] -Format-add spacing at end of page 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 user "rs232", 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 =====
-  * Many wiki readers aren't fluent in English. Please choose your words carefully.
+  * Please **choose your words carefully**. Some wiki readers aren't fluent in English. \\ \\
-  * 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 computing, and society in general, and is safer to use.
+  * 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 non-standard abbreviations/short forms. For example, don't use "FT" for FreshTomato. Using LAN is okay, as it's common terminology.
+  * Add a **meaningful title** to every wiki page. Format it with the Heading1 format.  \\ \\
-  * Avoid using the word "Note". It's overused and should be used only when something is unusually important. Using it constantly makes the text  lose its impact, and makes it more jarring to read. We'll develop some guidelines/standards for writing and formatting notes.
+  * **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. \\ \\
-  * Avoid using underlining. It's obsolete and inappropriate. Research shows it also makes things harder to read.
+  * **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 view other pages to see what text is capitalized and what is written in lower case (small letters).
+  * **Avoid underlining**. It's obsolete and makes things hard to read. \\ \\
-  * Please use a spell checker. Firefox's spellchecker works well for this.
+  * Check other pages to see which kinds of text content are capitalized \\ and which are written in lower case. \\ \\
-  * When referring to FreshTomato's menus, please indicate as: //Menu/Submenu . //  For example, //Administration/Admin access .//
+  * Check spelling with your browser's spell checker. \\ \\
-  * Avoid using quotation marks. They're almost never appropriate. If you're not sure, don't use them.
+  * **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 =====
-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. \\ \\
-  * Add a meaningful title for each wiki page, and format it with the Heading1 format.
+The wiki uses [[https://www.dokuwiki.org/dokuwiki|dokuwiki]] as its underlying software.
-  * Subheadings use the Heading2 format.
-  * Subheadings below that use the Heading3 format.
+It uses [[https://prosemirror.net/|ProseMirror]] as its editor.  \\ \\
-  * 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.
+  * **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 level node name-bottom level node name-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 level node name-bottom level node name-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 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. \\ \\
+  * **Avoid quotation marks**. They should be used only:
+    - When slang is used.
+    - When expressing something precise, separate from body text, such as a filesystem path. \\ \\
+  * **Avoid underlining**. It's been obsolete since the 1980s and makes text harder to read. \\ \\
+  * **Avoid using the word “Note”**. Put notes in the Notes section that exists \\ at the bottom of most pages.\\ \\
+  * Except in a code window, **command strings should be set in the** ''monospace'' font, \\ or in a callout box.\\ \\
+  * 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 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. In general, slang has no place on a technical wiki.
-  * Avoid underlining. It has been considered obsolete since the 1980s.
-  * Avoid using the word “NOTE”. There is a section titled "<Menu name> Notes" at the bottom of most pages.
-  * 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 set them off from the main text.
-  * Avoid using dividing lines. Better spacing, and other formatting methods work better.

FreshTomato Wiki

User Tools

Site Tools

Differences

Page Tools