Contents


Deprecated: please see new documentation site.



Here are a couple of style notes for creating new pages and the content on them.

Page Names

One of the most important things in a wiki is the names of pages. Some wikis segregate data into separate namespaces; here, instead, everything resides in the same namespace, which makes exhaustive searches easier, but means that page names must be considered carefully. There are really only two (and a half) rules for naming pages:

  1. A page's name should be unambiguous. This is the most important. Don't name a page System Messages, for example; that tells people nothing about the content. What system? What messages? 575 LED Error Messages, on the other hand, is an excellent page name; it is unambiguous as to what it means.
  2. Use parentheses for like groupings. For example, all of our Xen guests might be in the format [[IMAGENAME (Xen guest)]], and System Minutes (if we had such a beast) might be of the format [[DATE (HPC Systems Minutes)]]. There are two major benefits to this scheme:
    1. All Xen guests have (Xen guest) in their pagename, making them easy to search for; and
    2. Making 'pretty' Wikilinks to the pages is easy. If you put a link like [[wiki.loni.org (Xen guest)|]] on a page (note the pipe before the closing brackets), you get this link when you save the page: [[wiki.loni.org (Xen guest)|wiki.loni.org]]. This reduces typing for pretty links.
  3. Be reasonably consistent with page names. In a given section, there are de facto standards of page names. If there isn't one established yet, well, just make your names look nice together. For example, we generally prefer active page titles ([[Installing a CSM Cluster]]) to passive page titles, but this is purely a style thing.

All of that said, pages can be moved after the fact, but only administrators of the wiki can do so. Just ask one of the administrators to do it for you if you muck up the name.

Content

Mostly, don't worry about content style. Reasonable consistency with other pages is nice, but it's more important to have lots of ugly content than to have a tiny amount of pretty content. One of the benefits of the Wiki methodology is that someone can always come behind and tidy things up.

One important wiki content consideration is links to other pages. When you're writing a document, and realize it should link to another page, put the link there! Don't worry if the page doesn't exist yet. Follow the style guideline above for naming the link, but remember that you can use the "|" character in links to make the display text different. [[Adding LDAP Authentication to AIX 5.3|LDAP auth]] ends up looking like this: [[Adding LDAP Authentication to AIX 5.3|LDAP auth]]. That's a vast improvement over the wordiness of the actual link destination, but said wordiness is a good thing for the reasons given above.

Be bold!

Most importantly, be bold in adding new content. Want to document something? Go for it! Want to expand or correct someone else's page? Do it; don't worry about the details. We can always go back to previous revisions if necessary.

Use Templates

Templates provide a means of standardizing appearance and providing shortcuts (i.e. programming macros). You can create your own, or use any that already exist.


Powered by MediaWiki