Differences

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

--- style_guidelines [2021/09/22 02:11] – [Text Content Guidelines]-Added text content guidelines hogwild
+++ style_guidelines [2023/07/16 18:10] (current) – [Layout/Formatting Guidelines] -add that variables should be italicized 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 =====
-- 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.
-) 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.
-) 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 to distinguish them from the main text//. \\ \\
-  * 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. \\ \\
-  *

FreshTomato Wiki

User Tools

Site Tools

Differences

Page Tools