KRayWiki:Style

See Also : About KRayWiki

This is a work-in-progress style guide for wiki pages and text.

Font Reference

1. italics : ''

   Comments or annotations made outside the context of what is underway.

   In a procedure, for example, additional information not literally part of the required procedure; possibly a description of what is entered, as in username when an actual user name is required instead of the actual word "username" in the procedure.

2. bold : ''', or, a bold term in a definition: ; term : definition

   Minor titles to not appear in the outline.

   Proper names especially pertinent to the topic not easily falling into the bolded italics category.

   In a procedure, Window/dialog titles, controls section name, value/control names (not things the user does).

3. bolded italics : '''''

   file names, standalone command references, installed software package names.

4. monospace font : <kbd>value</kbd>

   assigned values, user input

5. <monospace font> : <kbd>&lt;Keyname&gt;</kbd>

   Indicates the user is generally expected to press the indicated key or keys.

   For certain special function keys, standard CamelCase key names are used (i.e. <PgDn>, etc.).

   An embedded + or - between multiple keys indicates use of a shift modifier (i.e. <Shift>+<PrintScreen>, etc.).

6. $ monospace font : <code>$ command</code>

   A console command to be entered by the user.

   Also, substitute $ with # when elevated permissions are required.

7. small monospace font : <kbd><small>console output</small></kbd>

   Console output, or, command results.

8. monospace font with colored background : <code>text</code>

   Excerpt text from a file (usually for a small subset of the file content).

   <pre>, or a <div> with similar style, is used for larger blocks of text.

9. [monospace font with colored background] : <code>[name]</code>

   Indicates a click of a button on a graphical user interface.

10. bold monospace font with colored background : <code>'''name'''</code>

    Indicates a click of a non-button widget on a graphical user interface. (i.e. radio button, window tab, etc.)

    For the bolded term found in term/definition markup, use ; <code>term</code> : definition instead.

Section Headings

Recommended use of headings and sub-headings is illustrated on the Style-Headings page, but a summary of usage considerations follow:

• Using headings automatically results in generation of an outline at the top of the page.
• Headings correlate to the HTML elements H1 through H6, so outlines are limited to six levels.
• Default formatting of headings does not necessarily lend itself to clearly delineating sub=sections of the document since.

  Font size is sometimes the only difference between headings and the size changes are not necessarily quickly identified by a reader - particularly as section length increases.

  When a page contains multiple headings, strongly consider use of additional HTML markup to improve readability and clarity.

HTML Support

MediaWiki generally allows use of HTML tags in wiki text. A relatively full listing of usable HTML elements with corresponding sample rendering appears on the Style-HTML page, but a summary of usage considerations follow:

• Customized CSS could potentially make use of some elements more useful.
  • Customized CSS introduces potential for complicating the style guide.
• HTML5 elements are not supported.

Page Names

Page names are constructed to closely align with wikipedia:Help:Categories. This make page name and category names fairly synchronized so that one could guess a category from the page name, and vice versa. The point of doing this is to embed the concept of topical organization in the minds of authors that create new pages. It is also an embedded reminder that pages usually should belong to a category. For example:

• A top-level topic index page might be named "OS-Linux".
• An OS- prefix could have been added if multiple operating system pages are anticipated.
• The use of a dash-prefix implies the page will reference an equivalent category ([[Category:OS]]).
• Since OS-Linux is such a "large" topic, it may be wise to anticipated that many OS-Linux-* sub-pages might exist at some point, and so the page name might also be used as a category name ([[Category:OS-Linux]]).

Category names components and page name prefixes are separated by dash (-) characters. The non-category prefix portion of a page name is joined to the category prefix with a dash character (-), and usually uses camel-casing when the name contains multiple words.

• Using the OS-Linux example, if an OS-Linux-Utilities page is needed to document a number of utilities on the same page:
  • It can be wise to use a non-plural page name as: terse names are better to limit name lengths (i.e. OS-Linux-Utility).
  • The name more easily suits a category name in case page content grows to a point it is advantageous to split a large page into sub-categories or convert it to an index for a group of similarly named subordinate pages. For example:

    OS-Linux-Utility-TextProcessing

    OS-Linux-Utility-HardwareInfo

    and so on.

• When multiple sub-pages of a page are created to break up large topics, even if a new category does not seem warranted, the subordinate pages are might be named as if the root page was a category (though this is not necessarily practical or required). For example:
  • Instead of:

    OS-Linux-Utility-TextProcessing

  • Even though an OS-Linux-Utility-Text category might not be warranted, one might consider:

    OS-Linux-Utility-Text-Filter

  • So other page names can use a common root that is easily converted to a topic if page count is sufficiently high.

    OS-Linux-Utility-Text-Editor

    OS-Linux-Utility-Text-Analysis

    etc.