You are here: Wiki > start > editors > stylemanual

Locked Page is locked

Table of Contents

Style Manual
Page titles
Internal Links
Back Links
More Information Required?
Simulation Documentation

Style Manual

This document contains information on how individual pages should be formatted, and how text should be structured.

Page titles

A page should always have a title in H1 style. That means all subsequent section titles should be H2 or lower. The written title should always be in plain English. The page name itself should be in lower case with words separated by underscores. Thus a page called "This Is It" should be called this_is_it.

With the exception of tutorials with numbered steps and a couple of other limited scenarios, do not number pages. Instead, give them meaningful titles. For example, it's easier for an author to link to "how_to:use_a_mouse" rather than "section_1:topic_53".

Apart from well-known acronyms, abbreviations should be avoided where possible. Conversely, ridiculously long page names should be avoided. Examples:

  • AHB, ARS - Ok, since they are common abbreviations in railways and in SimSig.
  • LE - Maybe it means Light Engine, maybe not. But since it's not common, don't use it.
  • a_potted_history_of_simsig_and_how_it_came_to_be - Let's be sensible: call it history_of_simsig or something.
    • =

The first time a term is referenced, such as something which is explained in the Glossary , it should be linked to that page. It is not necessary to link the same word or phrase multiple times within the same section, but it may be beneficial if the word or phrase appears later in a different section of the same page.

It does not always make sense to have specific back links in a page, such as "back to Glossary" from a Glossary term, or even just "Contents". This is because the user may have arrived at that page by other means and therefore "back" is misleading. The user can use the breadcrumb trail near the top of the page, the "You are here" hierarchy, or use the back button on the browser.

Back and forth links in a series of articles are also unhelpful if an author wishes to insert a new article mid-sequence, as the links on the existing pages also have to be altered - or, if forgotten, will be wrong.

More Information Required?

Where the author/editor of a page cannot complete the page for whatever reason, inserting the word TODO can help other authors/editors find such pages and complete the missing information. The same word can also be used where the information needs verification.

Simulation Documentation

Namespaces should be used for simulation manuals where there is more than one page. Thus, for simulation Zulu with pages Introduction, Body, and Footer would previously have been named:

  • ZuluIntroduction
  • ZuluBody
  • ZuluFooter
    • Instead the pages should be named:
  • Zulu:Introduction
  • Zulu:Body
  • Zulu:Footer
    • This makes a nice hierarchical structure to the Wiki and makes it easier to move pages around. It also removes the need for a "Back to contents" link since that will be in the "You are here: Mans > Zulu" links at the top.

The new namespaces are as follows, and should be used when creating new pages:

  • simulations:

    [simulationname]:[manualsection]. For example simulations:edinburgh:signal_diagram.

  • glossary:

    [term]. For example glossary:interlocking. This glossary should be used for railway terms.

  • ssterms:

    [term]. For example ssterms:multiplater. This glossary should be used for SimSig specific terms.

  • signallingprinciples:

    [subject]:[section]. For example signallingprinciples:detection:track_circuit.

Last edited by GeoffM on 15/09/2016 at 03:00