Differences

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

--- wiki:guidelines [2010/04/28 19:25]
jonyo re-wording
+++ wiki:guidelines [2014/09/25 16:55] (current)
@@ Line 1: / Line 1: @@
 ====== Guidelines ======
-Below are some basic guidelines we try to follow for this WIKI so that we can have a level of consistency.  We will be creating/updating these guidelines as needed.  ((Or in this case, creating guidelines to begin with...  We'll be working to create the guidelines soon.))
+Below are some basic guidelines we try to follow for this WIKI so that we can have a level of consistency.  We will be creating/updating these guidelines as needed.
+===== Page Index =====
+The page index, is what would be used to link to the page from another page in the WIKI.  The index will match the end part of the URL for that page as well.  For instance, the URL for the page you are currently viewing is:
+  http://geodesicsolutions.com/support/wiki/wiki/guidelines
+And the **page index** for this page is:
+  wiki/guidelines
+The index, in most cases, will closely match with the page's title.
+The index should use underscore **_** as the **word separator**.((Knowing what we know now about Google recommending the use of hyphen **-** over underscore **_** for the word separator, it may have been better to use hyphens, but we didn't, and it's too late to start doing it now.))
+Only alpha-numeric and underscores _ in the index.  Note that things like & can be used in the page title, but cannot be used for the page index.
+Index should be something simple and short ((Partially so the link to the page is shorter)).  The page title can be longer (although long titles should be avoided if possible), and prone to change over time, but the index will always stay the same so should be short and simple.
+Keep things that are more likely to change over time out of the index, such as "for_version_5".
+===== Page Title =====
+First, you need to know how to make a page title.  It's very simple, the **first headline on the page** is used as the page title.  If you look at the top of this page you'll see the first heading is [[#Guidelines]], and that is what the page title is used for as well.
+The page title is used for the link to the page, and in the page breadcrumb listed at the top of the page.  Keep this in mind when making a title for your page.
+**Including keywords in the title is great**((As long as the keywords relate to the page contents, of course.)) since it makes the page show up in relevant searches better, but **not at the expense of making sense**.  Make sure you are not over-doing keyword usage.  A good rule of thumb is to try to make the title as **short as possible**, while still being descriptive enough so that people know right away what the **page is for** without having to open the page and read the contents.
+Put what it is at the beginning of the file.  If you //must// add a few extra keywords to the title to make the page show better in searches, word it so the secondary keywords are at the end.  For example "Performance Tips for Classified and Auction Software" instead of "Classified and Auction Software Performance Tips", the former is easier to spot when you are skimming the menu for a page.
 ===== Use of Folders & Pages =====
@@ Line 19: / Line 49: @@
 ===== Admin Menu Sub-Pages =====
-All pages in the [[admin_menu/start]] section **must be [[#Empty Folder Pages]]**.  In other words, there can not be any pages with an index that ends in something besides /start, for any pages in this section.  There are 2 main reasons for this:
+In the admin panel, there can actually be "hidden" sub-pages((In the WIKI, you will see such hidden **S**ub-pages in the menu, and they will end in **[S]**.)).  On every page in the admin panel, there is a **help link** that links to this WIKI, directly to the WIKI page specific to the admin panel page currently being viewed.  The link is automatically created, based on the admin panel page's breadcrumb, and each link **always ends in /start** to account for the ability to have hidden sub-pages.
-  * With adding new functionality and features, new "hidden sub-pages" are added regularly.  It is much easier to start out a page as an [[#Empty Folder Page]]
-When you should use such "empty folders" instead of a normal page
-Each folder can have a page inside that folder, that is displayed when the folder itself is viewed.  Such a page will always end in /start since it designates the "start page" for a folder.
-When a page ends in /start, that designates the page as the "start page" for a folder.  Such pages will use a folder icon in the WIKI menu on the left side of the WIKI.
-There are also normal pages, that do not end in /start such as the page you are currently viewing.  These pages use a normal page icon in the left side WIKI menu, and will not be able to have sub-pages added that are "under" that page.
+**All pages** in the [[admin_menu/start]] section **must be [[#Empty Folder Page]]s**, due to the way automatic admin panel to WIKI page linking works as it is described above.  In other words, the index for every page in the [[admin_menu/start]] section **must end in /start**.
+The index for a page must match exactly with the link that is automatically generated for that page in the admin panel.  Click on the help link in the admin panel for that page to make sure you are using the correct index when you create a new page.
+For **admin menu categories**, on the start page for the section: Directly below the page title, add the following line, adjusting the breadcrumb as appropriate: <code html>Admin Menu Category: **Category > Sub Category**</code>
+Then below it, give a brief explanation of what type of things can be done in pages located in that section of the admin panel.  See [[admin_menu/admin_tools_settings/messaging/start|Admin Menu > Admin Tools & Settings > Messaging]] as a good example of this.
-In other words, when you click on "sub_folder", it displays the page "sub_folder/start".  When creating a new page, use these guidelines for whether it should be created as a folder start page, or just as a normal page.
+For **Admin Pages**, directly below the page title, add the line <code html>Admin Page: **Category > Sub Category > Page**</code>
+Then below it, give a brief explanation on what this page in the admin panel is generally used for.  See [[admin_menu/site_setup/general_settings/start|Admin Menu > Site Setup > General Settings]] as a good example of this.
-  * Sub-Folder of [[admin_menu/start]] - **Always end in /start** - In order to allow additional sub-pages to be added easily as new functionality is created, all pages in the [[admin_menu/start]] section must end in /start.  It is also required so that the automatic links from the admin panel link to the correct page in the WIKI.
+For **hidden sub-pages**((That is, pages that are sub-pages of another "main page" in the admin panel, that can't be accessed directly using the normal admin menu.  An example would be **Design > Manager > Edit File**, to get to that page you would go to **Design > Manager** then click "edit" for one of the files.)), the page title should end in [S].
-  * Page is a folder - It must end in /start if it is the page that displays when you click on a folder with sub-pages in it.
-  * It is likely that the page may have sub-pages added in the future - It can be tricky to convert a
 ===== Acronyms =====
-For any Acronym, the case matters!  Use the proper case for the acronymn, usually this will be all uppercase((But not always, for example MySQL it is common to have all uppercase except for the y.)).  This WIKI will recognize common acronyms and add a hover that tells what the acronym means, for example the acronym WYSIWYG.  If improper case is used, the WIKI will not recognize it and will not show what it stands for, for instance if you used wysiwyg((NOTE:  We break the acronym guideline here on purpose to illustrate the point of why the case matters on acronyms.)) instead of WYSIWYG.
+For any Acronym, the case matters!  Make sure you always use the proper case for the acronym((You can usually spot them easy enough, in Firefox it will have the red dotted line under the acronym as if it was misspelled.)), usually this will be all uppercase((But not always, for example MySQL it is common to have all uppercase except for the y.)).  This WIKI will recognize common acronyms and add a hover that tells what the acronym means, for example the acronym WYSIWYG.  If improper case is used, the WIKI will not recognize it and will not show what it stands for, for instance if you used wysiwyg((NOTE:  We break the acronym guideline here on purpose to illustrate the point of why the case matters on acronyms.)) instead of WYSIWYG.
-A few common Acronyms that are recognized by the WIKI: URL, WYSIWYG, WAMP, PHP, IP, plus a ton others.  If you find that an acronym is not recognized by the WIKI and you have used the proper case, let us know and **we can add it**.
+A few common Acronyms that are recognized by the WIKI: URL, WYSIWYG, WAMP, PHP, plus a ton others.  If you find that an acronym is not recognized by the WIKI and you have used the proper case, let us know and **we can add it**.

Geodesic Solutions Community Wiki

User Tools

Site Tools

Differences

Page Tools