Editing Tips

From CCMDB Wiki
Jump to navigation Jump to search

Editing a page in a wiki is quite easy - just click on the "edit" tab at the top. For the CCMDB wiki, you need to be logged on to edit. If you are involved with the CCMDB, contact p:Tina Tenbergen to have an account created.

Be bold!

The main idea of a wiki is that any of us can add, update and improve it. If you see a typo, a run-on sentence or something that is not stated clearly, edit it by clicking the edit tab a the top. Make the changes, don't be too concerned that you may have misunderstood or step on someone's toes. The wiki keeps track of all changes, and if something goes really wrong, you can revert any entry to an earlier version using the "history" tab.

When you write anything for this wiki, keep it short and concise - this is for information, not entertainment. When you find an entry getting much longer than what fits onto one screen, consider if it can be split into sub-entries. There is no hard rule there, just think of usability as a reference. Often point form (i.e. starting lines with a *) is is more suitable than full sentences.

Watch those versions!

When editing text, please make sure that you are editing the most recent version of the page and not a previous version otherwise interim edits will be lost! The most recent version of a page will have no revision information below the title unlike earlier versions. This is a quick visual clue to help guide you during the editing process. Also, if you end up on the edit page, there is a bold warning at the top of the edit box, e.g.,

Warning: You are editing an out-of-date revision of this page.

If you save it, any changes made since this revision will be lost.

Wiki mark-up - Wikipedia's Cheatsheet

Wikis use what is called a "mark-up" to show that something is a heading or a list item. If you are not sure how to do something in wiki mark-up, click on the "edit" tab of an entry that is set up the way you are trying to do.

For a quick start, you can look at Wikipedia's Cheatsheet.

Writing a new article

To begin writing an entirely new article there are several ways to go about it.

You can write the name for the new article at the end of the URL (i.e., after index.php) for the wiki. For our wiki that would look something like:

  • http://ccmdb.kuality.ca/index.php/My new article

Alternatively, you can add a wiki link to the article you are going to write to an existing article and save it. The link will show up in red font in the existing article. Either of these will bring you to a page stating that the entry does not exist. If you click on the edit link, it will take you to the wiki edit window.

When writing your article, be kind to other potential editors/authors and use whitespace appropriately. While the editor will quite happily allow you to scrunch everything together (for the most part) and still render the page properly, it does a disservice to the next editor. Use appropriate paragraph breaks, allow lists to stand on their own, etc. Refer to Wikipedia Tutorial for a guide to the basics

NOTE:While the CCMDB wiki uses the same platform as Wikipedia, the nature of the articles and how we use the CCMDB wiki is often quite different. So any reference to Wikipedia help should keep that in mind.

Linking an article

An article can be made much more useful if it is integrated into the existing knowledge base of the wiki by linking it to and from other articles. For example, instead of adding into this article how to log in (at the top), I added a link to an existing article on that topic. The advantages are:

  • it focuses the article on a single topic
  • it saves the reader time in case they are not interested in the related topic, or already know it
  • it avoids duplication
  • it allows making any necessary changes in only one place

Ideally, every article in a wiki is linked to and links to other articles, allowing the reader to move through the information in the way most useful at the time.

To link to a another wiki article, put it's name into double square brackets. To use a different word for the link itself, put a "pipe" character between the entry name and what you want to show in the text. For the login example above, this would be:

  • [[Logging on to the wiki|logged]]

Categorizing an article

In addition to links, wikis articles can be organized into categories. For example, there is a category called Category:IT_Instructions. The wiki automatically keeps track of all categories on the Special:Categories page.

To add a category to an article, add the following to the bottom of the article while editing:

  • [[Category:Name of the category]]

For example:

  • [[Category:IT Instructions]]

If the category you use does not exist yet, the wiki will create it and group all further entries with the same category on that category's page. Check the Special:Categories page before you create a new category to make sure a similar one does not already exist.

Tables in the wiki

The wiki markup for tables is somewhat complicated to set up manually. There is an excel sheet that converts a table to wiki markup automatically. You can download it here.