ARCC Wiki editing and formatting

From arccwiki
Jump to: navigation, search

Introduction

This wiki is intended to be a collaborative effort to share information and best practices related to research computing. Logging in with a UWYO account provides access to:

  • Edit pages whose name (in the URL) / title (at the top of the page) starts with "Research:"
  • Create new pages linked from an existing page that you can edit. Be sure to give any new page you create a name that starts with "Research:" and that indicates its relation to the page it is linked from.

Guidelines

The following guidelines include good practices for having web content work as intended for all users, including in different browsers, with keyboard navigation, with screen readers, and also to meet UW web accessibility requirements. The MediaWiki software that runs this site is designed to produce accessible web content when used as intended.

General considerations

  • Think about the logical structure of the content first, and use the appropriate HTML/wiki elements to implement the logical structure, only using appearance-based formatting for things not provided by a logical element. Some applications of this principle include:
    • Headings: For text that is logically a heading, use a heading element of the appropriate level — don't use bold or size styles directly to approximate the appearance of a heading. See the Headings section below for more detail.
    • Lists: For content that is logically a list (ordered or unordered), use the appropriate list element (rather than, for example, linebreaks or tables).
    • Tables: Don't use table elements for layout — only use table elements for things that are logically tables (e.g. a list of items with attributes like price, speed, length, temperature, color, etc.)
  • Aim for clear, concise and accurate information. If content contains a lot of repetition, or non-informative language, there is usually a way to improve it.
  • Legibility is important:
    • There shouldn't normally be a reason to change the size of text — the logical structure will determine the sizes of the different elements relative to each other, and users will be able to enlarge or shrink the text as needed in their browser.
    • Don't change colors to have a low contrast between foreground (e.g. text) and background. Note that for smaller text, more contrast is needed to maintain legibility.
  • Don't use features for purposes other than what they are intended, as this is likely to cause unintended consequences.
  • Content produced should always be valid HTML — if wiki elements are used correctly, this will be the case.

Headings

  • The page title is automatically created as a level-1 heading. For page content, headings of levels 2 through 6 are available using the following wiki markup:
    == Level-2 Heading ==
    
    === Level-3 Heading ===
    
    ==== Level-4 Heading ====
    
    ===== Level-5 Heading =====
    
    ====== Level-6 Heading ======
    
  • Organize the content of a page using a logical heading structure:
    • Don't skip heading levels (e.g. inside a level-2 section, don't put a level-4 heading without first being inside a level-3 section).
    • Using meaningful text for headings.
    • If a page contains 4 or more headings, a table of contents will be generated automatically (e.g. see the "Contents" box at the top of this page).

Lists

The HTML list types ordered lists, unordered lists, and definition lists can all be created using either wiki markup or HTML.

  • Wiki markup: Using wiki markup will generate valid HTML and is simpler for lists that don't require linebreaks inside their items. Wiki markup works well for lists containing sub-lists, including of different list types.
  • HTML: Where items in a list have a more complex structure (e.g. multi-line code fragments), the list can be created by instead using HTML list tags directly. Care must be taken to ensure that all tags are properly closed, and nested correctly, to obtain valid HTML.

The wiki markup for these types of lists is:

  • Unordered list:
* Item 1 of outer list
** Sub-item 1
** Sub-item 2
* Item 2 of outer list
* Item 3 of outer list
** Sub-item 1
** Sub-item 2
*** Item of list inside Sub-item 2
*** Item of list inside Sub-item 2
  • Ordered list:
# Item 1 of outer list
## Sub-item 1
# Item 2 of outer list
## Sub-item 1
## Sub-item 2
# Item 3 of outer list
#* First item of unordered list inside item 3 of ordered list
#* Second item of unordered list inside item 3 of ordered list
  • Definition list:

For definition lists, the title line is optional, and the definition may occur on the same line as, or the line following, the term. Both options are shown in the example below.

; Definition list title
; First term : First definition
; Second term
: Second definition

The above three types of lists can have any level of sub-lists and can mix which types of lists are used. The second example shows an unordered sub-list of an ordered list.

Images

All images that are uploaded and included as content of a page should have an alt tag in the HTML produced. (Purely decorative images, for example to create background texture, are best handled with CSS.) This is achieved by:

  1. Follow the "Upload file" link in the Tools section of the left-hand menu.
  2. On the Upload page:
    1. Use the "Browse..." button to select the file to upload.
    2. In the Summary box, type in a description if you like — it will show up on pages for managing/editing the file, but isn't used as a caption, alt tag, or any part of the HTML produced.
    3. Click the "Upload file" button.
  3. Edit the page on which to include the image, and insert the following wiki markup where the image should appear:
    [[File:Filename.png|alt=Description of image]]
    where Filename.png is the name of the file that was uploaded, and "Description of image" is the value to be used for the alt tag. Note that:
    • If "alt=Description of image" is omitted, then an alt tag whose value is the filename (which isn't generally a good value) will be used.
    • Additional styling of images — such as alignment, scaling, captioning, and borders — is available. For details see MediaWiki Help:Images

Links

Links to other pages in the ARCC Wiki site are internal links, and ones to pages on other sites are external links.

Creating links

Each of these kinds of links can be created with the following wiki markup:

  • Internal links: use double square brackets containing the page name:
    • Using the page name as the link text:
      [[Page name]]
      where Page name is the page name.
    • Using link text different from the page name:
      [[Page name|Link text]]
      where Page name is the page name, and Link text is the link text. This form may be useful for making Link text a shortened version of Page name.
  • External links: use single square brackets containing the page URL:
    • Without specifying link text:
      [https://mediawiki.org]
      where https://mediawiki.org is the URL of the page to link to. This form of link will produce HTML links with sequential numbers for the link text, for the links on a page to some site. It is often more useful to specify what the link text should be, which can be done using the link form below.
    • To specify the link text:
      [https://mediawiki.org MediaWiki]
      where https://mediawiki.org is the URL of the page to link to, and MediaWiki is the link text.

Using links

  • The process of adding a new page to the wiki is to add an internal link on an existing page which goes to a page name that doesn't yet exist, then follow that link to create the page.
  • External links are often useful for providing links to reference material, documentation, or manuals for software packages, languages, algorithms, etc.

Colors

  • For most content, it shouldn't be necessary to adjust the color.
  • When using color:
    • Be aware of whether or not the color is being used to convey information.
    • Be aware of foreground, background, contrast, and focus.
  • If color is being used in a way that is informative (e.g. in an image that is a map), then:
    • Test the content for being able to distinguish between colors with common types of color-blindness. At a minimum, view the content in grayscale. Preferably also test for perceptibility with red-green deficiencies. (Please contact ARCC if you need more information or help doing this.)
    • Also include the information conveyed by color by some other method, such as alt tags on images (see the Images section above for details), or in the text of the page.

Further information

  • If you have any questions about adding/editing content, need help with it, or are planning to add a lot of content (e.g. a new section of related pages), please contact ARCC to discuss it.
  • Further information about wiki markup is available at MediaWiki Help:Formatting
  • Details about web accessibility are available at MediaWiki accessibility guide