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
Next revisionBoth sides next revision
style_guidelines [2021/09/22 02:11] – [Text Content Guidelines]-Added text content guidelines hogwildstyle_guidelines [2021/09/22 04:52] – [Text Content Guidelines] hogwild
Line 1: Line 1:
 ====== Style Guidelines (Wiki Edits) ====== ====== Style Guidelines (Wiki Edits) ======
  
-=====  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 @rs232, 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 =====
 +  * Many wiki readers aren't fluent in English. Choose your words carefully. 
 +  * 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.\\ Wi-Fi, however, is a standard term across computing, and society \\ in general, and is safer to use.
 +  * Avoid non-standard abbreviations/short forms. For example, don't use \\ "FT" for FreshTomato. Using LAN is okay, as it's commonly known.
 +  * 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 guiidelines/standards for writing and formatting notes.
 +  * Avoid using underlining. It's obsolete and inappropriate.
 +  * Please view other pages to see what text is capitalized \\ and hat is written in lower case (small letters).
 +  * Please use a spell checker. Firefox's spellchecker works well for this.
 +  * When referring to FreshTomato's menus, please indicate as: //Menu/Submenu . \\ //For example, //Administration/Admin access .//
 +  * Avoid using quotation marks. They're almost never appropriate. \\ If you're not sure, don't use them.
 +  * Please use rounded brackets () . Square brackets are generally not \\ appropriate here.
  
-- Do NOT use abbreviations that aren't common/standard 
  
-in the industry.+===== Layout/Formatting Guidelines =====
  
-Not everyone +Following style guidelines makes pages easier to understand, more pleasant to read, and easier on the brain and eyes.
- +
-e.g. "wl" does not equal wireless to anyone who +
- +
-1) doesn't use Linux or +
- +
-2) doesn't use open source +
- +
-e.g. Don't use "FT" when not everyone will recognize it. +
- +
-Anyways, the whole wiki is about FreshTomato, sot there's no need +
- +
-to write "FT". +
- +
-- 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.\\  +  * Add a meaningful title for each wiki page, and format it with the Heading1 format. 
-  * Add a meaningful title for each WIKI page, and format it with the Heading1 format. +  * Subheadings use the Heading2 format. 
-  * Indicate menu paths using notation like this: "navigate to //Administration/Admin Access//." (use / to separate //italicized// menu nodes). +  * Subheadings below that use the Heading3 format. 
-  * Use the standard Tomato theme for screenshots. +  * Indicate web interface menu paths like this: "navigate to //Administration/Admin Access//." (Use / to separate //italicized// menu nodes). 
-  * {{:pasted:20210921-184547.png}} +  * Always use the standard Tomato theme when taking screenshots. \\ {{:pasted:20210921-184547.png}} 
-  * 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. +  * 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.
   * Avoid underlining. It was considered obsolete since the 1980s.   * Avoid underlining. It was considered obsolete since the 1980s.
-  * Avoid using the word “NOTE”. A NOTES section can be added using Heading2 at the bottom of a page. +  * Avoid using the word “NOTE”. We are considering adding a NOTES section at the bottom of each page formatted with Heading2. 
-  * Command strings should be emboldened, like this: **ssh root@192.168.10.1** +  * Unless they are in a code window, command strings should be emboldened, like this: **ssh root@192.168.10.1** 
-  *+  * Variables should be italicized. 
 +  * Avoid using dividing lines. Better spacing, and other 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