Rules to Better Websites - Writing Rules

Hold on a second! How would you like to view this content?
Just the title! A brief blurb! Gimme everything!
  1. Do you know when to write a rule?

    The purpose of a rule is to effectively establish and record a process to guide employees in their day to day activities.

    Rules facilitate:

    • Consistency
    • Coherent instruction
    • A high standard of documentation
    • Better understanding of processes
    • Efficiency improvements

    Only write a rule after the situation has happened more than once – chances are it will happen again and a rule/standard should be created.

  2. Do you use the correct Rule structure?

    Your rule should be structured as follows:

    • Heading as a question
    • Why this rule exists and description
    • Bad example
    • Good example
  3. Do you have a master template for your website layouts?

    Consistency across your similar pages (such as standards pages in this case) is very important and should be made easy to implement.

    Guidelines and standards for the SSW website pages can be found at SSW Web Design References .

  4. Do you phrase the heading as a question?

    By forming the heading as a question you are encouraging the reader to answer with a simple yes or no. When the answer is no, it is clear that the rule has been broken and will need to be corrected.

    Phrase the heading as a question. 

    Bad example – the heading isn’t a question.
     Do you consider phrasing the heading as a question?

    Good example – the heading is phrased as a question.
  5. Do you give implementation examples where appropriate?

    By giving examples you are demonstrating clearly to the reader how he/she can implement the rule correctly. It is better to position an example of the best possible scenario last so that the reader is left with a clear example in his/her mind as to what is required.

  6. Do you label your example with a tick/cross followed by the word Figure:?

    Always use a green tick for a good example and red cross for a bad example followed with a label “Figure:”?

    Bad example - background colour is manually added to <tablegt; tag

    Bad example – example isn’t labelled with the X symbol followed by ‘Figure:’ 
    Figure: Bad example - background colour is manually added to <tablegt; tag
    Figure: Good example – It is clear that this example is incorrect.
    Figure: Good example - background colour is automatically added to <tablegt; tag
    Figure: Good example – It is clear that this example is correct.
  7. Do you always get your rules proof read?

    It is important to have high quality text to communicate your message. If your grammar, spelling and expression are poor, the reader may be left confused and have the sense that you really aren’t writing thoughtfully and with authority on the subject.

    Always get a rule proof read and edited by a good English speaker who can assess whether or not your rule communicates its message and conforms to company standards, and who can find any errors in spelling, grammar and punctuation.

  8. Do you avoid duplicating content?

    ​​Every time you decide that a process should be documented, it’s important to double check that the content does not already exist. 

    Spending 5 minutes Googling can save you a lot of clean up and maintenance later.

    Figure: You should think twice before adding content. As a great Australian Kerry Packer once said: "If you want to pass a new law, why don't you do it only when you've repealed an old one?"

  9. Figures - Do you add useful and concise figure text?

    ​When you add an image to a website or application, it is so useful to add a figure underneath it to describe your image. Tip: Prefix it with the actual word "Figure: ".

    (This is the same as how Microsoft Word does it when you add a caption.)

    It's the best way of ensuring you catch users' attention to the content of your page. When you're scanning a newspaper for interesting articles, you'll check out the pictures, read the accompanying description, and if it sounds interesting you'll go back and read the article​.​

    Users read websites in a similar fashion. Catch their attention with an image, and then keep it with a useful description. Don't just describe what the image is; say what it's used for in the context of the document.

    Good Caption
    Figure: Good Example - Some nice useful text describing the image

    It is especially important that images and captions serve a purpose, as opposed to graphics which are there solely for design. 

    Tip #1 - Bold your captions


    Figure: [Description…] (not bolded)


    Figure: [Description…] (bolded is best)

    Tip #2 - Describe the actions 

    Especially for screenshots, it is a good idea to have your figure describe the action the user would take:


    Figure: This is the screen


    Figure: On the screen, choose the execution method

    A good example of this can be seen in the figures at SSW Code Auditor User Guide page. 

    Tip #3 - Give bad and good examples 

    It's recommended that you use "bad" and "good" examples to clearly explain the DOs and DON'Ts.
    Bear in mind to always show the bad example first, then good example, like below:

    To print your document:
    1. Select File | Print. The Print dialog should now show.
    2. Select the number of copies and click Print. The file should now print.

    Figure: Bad Example - Using 'should' implies uncertainty

    ​To print your document: 
    1. Select File | Print. The Print dialog is shown.
    2. Select the number of copies and click Print. The file will now print.

    Figure: Good example - Using present or future tense implies confidence

    Related Rules