Structural guide-lines: How to lay out Help Pages, and editor short-cut keys

This document shows how a typical help page should be laid out, and details some "short-cut-keys" which aim to make it quick and easy to produce content which has a clear, standard layout. 
Ensuring that all Help pages are styled in a uniform and standardized way makes it far easier for users to understand them.
While the HTML Editor strongly limits the freedome of expression of writers, this is done with the goal of making the resulting content easier to digest for the user.

All documents are created by typing in text and adding

• Basic HTML heading-styles: H1, H2, H3, H4. 
  H1 is the "top-heading", H2 and H3 are just "lower level" headings. H4 includes a vertical line on its inner edge and is indented.
  short-cut: [ctrl]+[shift]+1, [ctrl]+[shift]+2 etc.
• Bold-text for in-line emphasis.
  short-cut: [ctrl]+b.
• A "Tip" style, where the text is presented in a box to stand out clearly.
  short-cut: [ctrl]+[shift]+5.
• Standard "numbered list" and "bullet list" options.
  short-cut: Type "1 + . + [space]" to start a numbered list. Type "* + . + [space] to start a bullet list (like the one you are reading)
• A standard "Table" style.
  short-cut: [ctrl]+[shift]+6, or select "Insert table into document" from the editor's context-menu.
• An "Image caption" style.
  short-cut: [ctrl]+[shift]+7 
• A "Code" paragraph style to show computer-programming languages.
  short-cut: [ctrl]+[space]+8
• A standard paragraph style.
  shoft-cut: [ctrl]+[shift]+0

 

It is not intended that those writing Help Items should "freestyle" and add other looks and styles to the help. Help is intended to be structured and clear and follow standard stylistic lines. The Orixa system holds a default style-sheet, which is used to style all Help pages, but each time the component is used in the application a different StyleSheet can be added and stored, allowing a lot of flexibility. This style-sheet is a CSS-HTML formatted text file. Once changed all the Help Items will be formatted following its style-mark-up.

While it is accepted that Help pages may contain links, they are really supposed to be read as documents, rather than "clicked through" as a series of links. The concept is that the user will navigate around help using the search-facilities in the System Help Tree-view, rather than within the documents themselves. Therefore each document should be kept reasonably short and "punchy".

Examples of styles (This is an "H2" heading, marked-up as "<h2>")

Sub-heading (This is an "H3" heading, marked up as "<h3>")

Indented emphasized text. This is intended to be used to summarize the contents of a section of a document. (marked-up as <h4>)

Tip (marked-up as <p class="tip"> in the raw data of the record)
 

This is a "tip" for example it can be used to add any simple clear text. It is not intended to "shout out" as much as the "h4" emphasis (above below the table). It is more for summary points at the end of a document, or at the end of an important section.

The "Tip" text is supposed to say, "if you are glancing through this text, please stop and read this section, as it is worth reviewing."

 Numbered or "Ordered" List (marked-up as <ol> and <li>)
 

1. Numbered or Ordered points and lists can go in a numbered list
2. They are marked as "ol" and "li", and display like this.
3. The idea is that they are not much more intense than standard text.

Numbered lists are quite frequently added to the second column of a Two-coloumn-table. Then the numbers used in them can match up with the numbers used to highlight points in the screen-shots.

SQL Code style (marked-up as <p class="SQLScript">)

SELECT SomeFields FROM SomeTable 
WHERE OneField LIKE 'Something' 
ORDER BY OneField

Example Tables

Explanation table

an image would be added here.	This is an example of an "explanation table". It is 2 columns with 1 row for each image. The images can include red icons with numbers to highlight areas of importance.
other images would be included ...	explanation text is included

Data / Information Table

	Data 1	Data 2
Something	With some data	And some more data
More	Other example text
More

The 2 table styles are intentionally similar. The "Explanation table" is always 2 columns, and does not have a "header row." It's main use is to guide the user through steps in a learning process, usually with images.

The data / information table has a freer structure, with multiple rows and columns acceptable as per the user's requirement.

TO ADD TABLES: Use the short-cut key [ctrl]+[shift]+6, or right-click and select "Insert Table into document