The User Documentation site - adding/modifying content

Stylistic guidelines

  • It sounds obvious but content should only appear in one place. This unfortunately was not the case in our previous documentation site(s).
  • Avoid making your page too long. Try instead to break it down into smaller chunks and have a summary page with links to the other smaller pages.
  • Avoid using expressions like 'click here'. Links ideally should not be buried within the text of a line but should appear clearly on a line of their own.
  • Make sure that spelling and grammar are correct smile
  • Using all capital letters in a header appears to be perceived as bad practice.
  • Only the first letter of a header/title should be in capitals, unless a commonly used abbreviation is being expanded.
  • Title pages should not be centered.
  • Avoid italics, use emphasize (<em>) instead.
  • Avoid bold - use <strong> instead.
  • Avoid the use of colloquialisms. For example "You need to do something" should be written as "Do something".
  • Avoid platform-specific references unless they are really necessary. For example try to say dice instead of f13 or sl5.
  • When copying HTML from another site, be aware that drupal seems to do more in the way of formatting so check that all html tags are necessary. (You may find that they are not.)
  • When constructing a table, make sure that all HTML flags are in lower case. Upper case flags do not give the results you might expect! They can cause unwanted white space.
  • Make sure line breaks are in the correct place!
  • When referencing a command line instruction, use the pre tags.

General structure

  • The documentation site ( has a number of regions :-
    • A top bar with a search box
    • A left side-bar with a structured menu.
    • A middle content body section
    • A right side-bar with a table displaying the current system status and a dropdown menu titled "Choose a Topic". On the home page only, the right side-bar also lists pages which have been recently edited.
  • Content types - each drupal web page is an instance of a particular content type. The computing help drupal site has four content types:
    • Page - almost all our web pages will be of this type. Allows full html and attached files.
    • Restricted page - identical to Page, but only readable by authenticated users
    • FAQ - a simple web page which is added to the FAQ section.
    • Status Page - a simple page that is displayed in the system status box in the right side-bar.
  • URLs - Internally to drupal, all content is essentially stored in a flat structure. Each page is known as a node, and is identified by e.g. /node/34 . This isn't particularly meaningful to users, so we use URL aliases to present the user with more user friendly URLs. Although URL aliases can present a hierarchical URL structure, we have decided to implement a flat URL structure (with the exception of FAQs, which live under the /FAQ branch). URL aliases can, in theory, be changed at any time but it's important for end users that they remain as static as possible so that, for example, bookmarked pages continue to work.
  • Tags - each page can be tagged with one or more keywords. This makes it easy for the user to ask for "all pages related to MacOS" or "all pages related to Printing". The user can display all pages with a specific tag by using the "Choose a Topic" menu in the right side-bar. You can add new tags, but note that the site editors have editorial control over tags and may consolidate with another tag. Please keep tags short-ish - otherwise formatting of the "Choose a Topic" menu will look odd.
  • Menu - the menu in the left side-bar is intended for users perusing the site to see what services are available etc. All services should be listed under the "Services" sub-menu. Note that certain commonly used services have been promoted to the top menu. Unfortunately, a page can have only one menu entry. The Menu is subject to editorial control.
  • System status table - each entry in this table is a link to a page, of type Status Page, providing fuller information on the status of the given service.The Scheduled Downtime entry in the table links to a page which should be used to announce scheduled downtime of services. The colours have the following meaning :-
    • Green - service working normally (or no downtime scheduled)
    • Yellow - a partial failure (or scheduled downtime) of the service (eg a small number of AFS servers down)
    • Red - a major failure (or scheduled downtime) of the service (eg a majority of AFS servers down)
  • Workflow - newly created pages of type Page and Restricted page are not published by default. This means that they won't be visible to end users and won't appear in the Recent Changes list on the home page. This allows you to work on content over time and only publish it once you are completely happy.
  • Reviewed date - each page has a Last Reviewed date. For new content this will be set to the date of initial creation. For modified content, this date should only be updated if you are entirely certain that the content is still up-to-date. It should not be updated for simple edits to correct spelling/grammar or broken links. There is a list of all "Last Reviewed" dates. Please check it to see if any of your pages need a review. The list is also linked from the right hand column of pages.
  • FAQs - FAQ pages live under the /FAQ branch. Visiting the /FAQ index page will display the FAQ entries in decreasing frequency of access.
  • Note that there is no edit locking. If two people attempt to edit a page simultaneously, the first person to submit a change will win.

Modifying a page

  • You have to be authenticated, so connect using https.
  • Navigate to the page that you wish to edit.
  • Select the Edit tab at the top of the content body section
  • Make your changes
  • If you have made major changes to the page and you are certain that all the content in the page is still valid, update the Last Reviewed date field. Do not do this for minor corrections.
  • Remember to save your changes (Save button is at foot of page)

Adding a new page

  • You have to be authenticated, so connect using https.
  • Click 'Content' (top left), click 'Add Content' and select the 'Page' content type.
  • Add a meaningful title. This is important as this is what will identify the page when it matches a tag (topic) search. Do not tick the "Exclude title from display" box.
  • You can then start typing in the 'Body' box. By default, the text format is full HTML but you may want to select another option e.g. filtered HTML from the box directly below. Do not start with an h2 header as the page will then appear to have 2 headers.
  • To reference another page on the site, you must use standard html hrefs, eg <a href="/escalation"> Please do not reference a page, from another already published page, a page which has not yet been published.
  • You can also add a summary by clicking 'Edit Summary' above the 'Body' box. Please add a summary, as the tag searches sometimes struggle to show your page properly if you don't.
  • Directly below the body box, you can upload any file attachments. You can add an unlimited number of file attachments.
  • The next box to be completed is the one called 'tags'. Use this to tag the page with any keywords that you think would help a user identify the content of the page. Look through the existing tags (in the Topics menu on the right) and add all relevant tags to your page. Tags are an important way to discover pages so please take a minute to do this properly. You can have an unlimited number of tags per page but they need to be comma-separated. Auto-completion has been set up so that any tags that match what you are typing will be shown and can be selected.
  • Under tags, you can select the Unit that is responsible for the particular page. It currently defaults to US. This will then be used to identify pages that have not been edited/reviewed for a period of time and allow us to email the particular Unit.
  • You then need to decide whether you want to create a menu link. The default is NOT to create one. However, if you want to have the thumbnails along the top of the page, a menu link is required.
  • As soon as you click 'Provide a menu link', further options will be displayed - Menu link title, description and Parent Item. Under Parent item, you can scroll through the menu and decide where this page should appear on the menu.
  • By default, an automatic URL alias will be created on the basis of the page title. If you don't like the auto-generated URL, you can uncheck 'Generate automatic URL alias' and optionally specify one of your own. Please keep the URL structure flat.
  • By default, a new page is not automatically published. Once you are happy with the page, and wish to publish it, you should edit the page (see Modifying a page, above), click on "Publishing Options" (in the left hand menu towards the bottom of the page) and check 'Published'. Please do not reference a page, from another already published page, a page which has not yet been published.
  • Save your changes (Save button is at foot of page)

Adding file attachments to a page

  • Edit the page (as for Modifying a page above)
  • Add file attachments to a page using the section below the content body box. You can add an unlimited number of file attachments.
  • A file attachment can be no larger than 2MB.
  • By default, the filenames of your attachments will be displayed in a table below your page's content. You can provide a more meaningful label for your attachment by completing the 'Description' entry. You can disable the display of an attachment in the table by unticking the 'Display' box - this is useful when you have attached images that you are displaying in-line on your page.
  • For pages of content type 'Page', the url path to an attached file is /sites/default/files/{filename}
  • For pages of content type 'Restricted Page', the url path to an attached file is /system/files/{filename}. Files attached to Restricted Pages are only accessible by authorised users.

Adding a page for authenticated access only

Editing an entry in the status table

  • Visit the entry by clicking on the link in the status table.
  • Select the Edit tab
  • Add/modify content. We may, in time, develop a convention for formatting status entry content.
  • Remember to save your changes (Save button is at foot of page)

Changing the colour of an entry in the status table.

  • Visit
  • Select the Edit tab
  • Each colour is implemented using a CSS class. Change the class in the line for the service you wish to modify to one of serviceup for green, servicewarning for yellow, servicedown for red.
  • Remember to save your changes (Save button is at foot of page)

Adding a question to the FAQ

  • Click 'Content' (top left), click 'Add Content' and select 'FAQ'.
  • You will be prompted to fill in the question and an appropriate answer.
  • Keep the answer short - linking to an existing page where appropriate. (If the question cannot be found in any of the existing pages, then it needs to be added. The FAQ is NOT an opt-out for writing end-user documentation!
  • Change the text format to Full HTML if needs be but leave everything else as default.

Deleting a page

  • Once a page has been deleted, it has gone forever. The only way to restore it is to restore the whole site from a backup.
  • If you wish to delete a page, you should unpublish the page and mark up the page (in the content) that the page is obsolete. The editors will periodically delete pages which have been unpublished and marked up. This workflow should protect us from inadvertent page deletion.

-- AlisonDownie - 15 Jun 2012 -- AlastairScobie - 06 Feb 2013

Topic revision: r28 - 27 Mar 2015 - 15:39:36 - ChrisCooke
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies