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
Last revisionBoth sides next revision
style_guidelines [2021/09/22 02:11] – [Text Content Guidelines]-Added text content guidelines hogwildstyle_guidelines [2023/07/16 18:06] – [Text Content Guidelines] -formatting hogwild
Line 1: Line 1:
-====== Style Guidelines (Wiki Edits) ======+====== Style Guidelines (Wiki Editing) ======
  
-=====  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 be able 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. 
  
 ===== Text Content Guidelines ===== ===== Text Content Guidelines =====
  
-- Do NOT use abbreviations that aren't common/standard+  * Some wiki readers are not fluent in English. Please, choose your words carefully. \\   \\  
 +  * 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. \\ \\  
 +  * 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. \\ \\
  
-in the industry. 
  
-Not everyone+===== Layout/Formatting Guidelines =====
  
-e.g. "wl" does not equal wireless to anyone who+Following style guidelines makes pages easier to understand, more pleasant to read, and easier on the brain and eyes.
  
-1) doesn't use Linux or+The FreshTomato wiki uses [[https://www.dokuwiki.org/dokuwiki|dokuwiki]] as its underlying software. It uses [[https://prosemirror.net/|ProseMirror]] as its editor.
  
-2) doesn't use open source+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).
  
-e.g. Don't use "FT" when not everyone will recognize it.+ \\
  
-Anyways, the whole wiki is about FreshTomato, sot there's no need+  * 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.
  
-to write "FT". +\\ {{:pasted:20210921-184547.png|A screenshot in the Standard Tomato theme}}  \\   \\
- +
-- Avoid use of the word "Note". It's being used way too often. +
- +
-It should be used only when something is unusually important. +
- +
-Using it constantly is like using underlining constantly, it causes +
- +
-the text to lose most of its impact, and it makes it more jarring to read. +
- +
-We will eventually decide on a standard for formatting +
- +
-for different levels of information, warnings, etctera. +
- +
-- Avoid using any underlining. Underlining is consider by those +
- +
-in the print, web and type industries to be mostly obsolete. It was +
- +
-appropriate when typewriters still existed, but now that we have +
- +
-all the tools of digital layout/type, there's almost never a need for it. +
- +
-And it makes things harder to read. +
- +
-- Please keep with the standard formatting conventions being +
- +
-used for type, such as (sub)Heading levels and body text. Changing things +
- +
-from standard formatting makes things confusing and harder to read. +
- +
-It will also make future changes to formatting more difficult and time-consuming. +
- +
-- Please be careful to spell words properly, or if you just can't be bothered, +
- +
-use a browser-based spellchecker, such as the one in Firefox. +
- +
-There's no reason at all for spelling errors these days. +
- +
--Please, no underlining. As I mentioned upthread, underlining comes from the +
- +
-typewrite age, and is now considered almost completely obsolete. Almost +
- +
-any standard type of formatting works better. +
- +
-- Please avoid writing "NOTE" or similar, as it's used way too often. +
- +
-Better formatting (which I'm working on)Seeing +
- +
-the word note is supposed to make something stand out, but when it's +
- +
-used so often, it just does the opposite. Sort of like the way some people +
- +
-bold constantly. I loses its effect. Eventually, better formatting will make +
- +
-this obsolete anyways. +
- +
-When referring to menus, we've mostly been using frontslashes. +
- +
-For example, +
- +
-"navigate to Administration/Admin access." +
- +
-I think this works fairly well, and is easy to read. +
- +
-There's no need to use quotation marks. +
- +
-- As rs232 was always reminding us, please remember to +
- +
-take screenshots with the Tomato style active, so we have consistency. +
- +
-Also, black screens of different resolution are sometimes really hard +
- +
-to read, at least on my monitor. +
- +
-Please use quotation marks only when necessary/appropriate. +
- +
-Quotation marks are used for something someone said, something +
- +
-that is an expression, slang and similar. They're not needed and make +
- +
-no sense for common terminology. For example, the word keypair +
- +
-doesn't need quotation marks, because it's a common expression +
- +
-in encryption. There's no need for quotation marks 99.9% of the +
- +
-time. If you're not sure, please leave them out. +
- +
-- If you're not going to do much formatting, please at least +
- +
-try to use Heading1 for the title so the page has a proper title on the top. +
- +
-Please use rounded brackets () instead of squared brackets. They +
- +
-are more appropriate, with limited exceptions that I won't discuss +
- +
-here. +
- +
- +
-===== Layout/Formatting Guidelines =====+
  
-  * Following these guidelines makes the wiki easier to understand, and easier and more pleasant to read.\\  +  * Avoid quotation marks. In the context of this wiki, they should be used only: 
-  * Add a meaningful title for each WIKI page, and format it with the Heading1 format. +    * When slang is used. 
-  * Indicate menu paths using notation like this: "navigate to //Administration/Admin Access//." (use / to separate //italicized// menu nodes). +    * When expressing, something precise separate from the text body, such as a filesystem path. \\ \\ 
-  * Use the standard Tomato theme for screenshots. +  * Avoid underlining. It's been obsolete since the 1980s. It makes text harder to read. \\ \\  
-  * {{:pasted:20210921-184547.png}} +  * Avoid using the word “NOTE”. There is a section titled: "<Menu name> Notes" at the bottom of most pages for notes. \\ \\  
-  * Avoid using quotation marks except where absolutely appropriate. Quotation marks are generally only appropriate when quoting something someone said or wrote, or when slang/colloquialisms are used.  +  * Unless they are in a code window, command strings should be set in the ''monospace'' font, or in a callout box. \\ \\  
-  * Avoid underlining. It was considered obsolete since the 1980s. +  * Variables should be italicized. \\ \\  
-  * Avoid using the word “NOTE”. A NOTES section can be added using Heading2 at the bottom of a page. +  * Process/Module names should be italicized to distinguish them from the main text. \\ \\  
-  * Command strings should be emboldened, like this: **ssh root@192.168.10.1** +  * Avoid using dividing lines. They are mostly obsolete. Better spacing, and modern formatting methods work better. \\ \\
-  *+
  
  
style_guidelines.txt · Last modified: 2023/07/16 18:10 by hogwild

Page Tools

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki