Difference between revisions of "PC-BSD® Wiki:Style Guidelines"

From PC-BSD Wiki
Jump to: navigation, search
(Categories)
(Collation)
Line 87: Line 87:
 
; Logical
 
; Logical
 
: Putting things in order of precedence; from first task to last task.
 
: Putting things in order of precedence; from first task to last task.
:: 2. Pre-Installation Tasks
+
:# Introduction
:: 3. Installing PC-BSD
+
:# Pre-Installation Tasks
:: 4. Post Installation Configuration and Installation Troubleshooting
+
:# Installing PC-BSD
 +
:# Post Installation Configuration and Installation Troubleshooting
  
 
; Quality or significance
 
; Quality or significance

Revision as of 21:14, 11 July 2012

Contents

Objective

The purpose of defining how pages on the wiki should be created, is to help maintain consistency by having a set guideline, and to enable easier translations of the site into other languages.

Text

The guideline for actual text content may be under continual refinement with frequent additions until nearly complete. In areas that are not yet defined or incomplete, a reasonable default can be taken from the Wikipedia:Manual of Style.

Typographic Conventions

The PC-BSD Handbook uses the following typographic conventions:

bold text: represents a command written at the command line. In usage examples, the font is changed with any command output displayed in unbolded text.
italic text: used to represent device names or file name paths.
bold italic text: used to emphasize an important point.

Language usage and word choice

Variety
Use words and phrases with the same meaning; multiple types of sentence structure.
Contractions
In place of don't, can't or won't, use do not, cannot, or will not.
Brand names
Use web search instead of Google search.
Idioms
Use proper and precise wording.
Watch closely should be used instead of keep an eye on.
Crashes or fails in place of gets a blue screen of death.
Idioms described on wikipedia.
Slang
Use precise rather than colorful or regional terms, however some technical jargon is allowable especially if explained or defined.
Open a browser to pcbsd.org would be used instead of surf to pcbsd.
Slang described on wikipedia.
Jargon described on wikipedia.

Hypertext Links

Internal
The URL is within the PC-BSD wiki.
Use [[page name]] or [[page name|alternate text]]
External
The URL is for a location outside of wiki.pcbsd.org. Most places where an external link may be used, there is alternate text shown, which means for a printed handbook, there must be a footnote to provide the actual URL. Those rare places that do not provide alternate text but show the actual URL, do not need the citelink method below.
For the link use {{Citelink|url=complete URL|txt=alternate text}}
Also place one {{refheading}} at the bottom of the page, above the category links section.
Special External
The URL is for a site not part of the PC-BSD wiki, but has a defined interwiki shortcut such as for wikipedia.
Use [[wikipedia:page name]] or [[wikipedia:page name|alternate text]]
A template for this will hopefully soon work similar to the above external link, but allow choosing interwiki sites.

Special Characters

Traversal of menus or windows
use an arrow (➜) as in the example:
PC-BSD control panel ➜ System manager ➜ System packages tab
This is an IS0 8859-1 character but may appear as a box in other charsets such as unicode UTF-8.

Lists

Bullets

There are two types of bullets in use:

1. A bulleted list which begins uppercase. Whether or not it ends in punctuation depends upon the size of the list. For example:

  • the What's New in 9.1 list uses sentences to describe the features so ends in a period. Use this type of list when the list includes a description large enough to warrant at least one sentence.
  • the Minimum Hardware Requirements list uses few words per item. Since the individual items do not warrant a sentence, this type of list does not end in a period.

2. A bulleted list which begins with bolded text (typically the name of a menu item). The bolded section is capitalized to match the name of the menu item and followed by a colon (:). The sentence following the colon begins lowercase and should be worded so that the bolded item is the beginning of the sentence. An example is:

Size on Disk: indicates the amount of space being used by the jail.

In this example, the menu item appears as "Size on Disk" (mix of upper/lowercase), "indicates" is lowercase and is worded so that it reads as one sentence (including the name of the menu item). Because it is a sentence, it ends with a period.

To ensure that the PDF and EPUB versions format correctly, use a hard enter between the items in a bulleted list.

Collation

The information should first be placed in logical order, followed by quality or significance, then sorted in alphabetical order, next by chronological order, and finally by ordination. It may be noted that the entire collation section follows logical order, due to the order described in the first sentence. Examples below are taken from the PC-BSD Users Handbook#Table of Contents. The Errata page shows how chronological and ordinal organization may be used.

Logical
Putting things in order of precedence; from first task to last task.
  1. Introduction
  2. Pre-Installation Tasks
  3. Installing PC-BSD
  4. Post Installation Configuration and Installation Troubleshooting
Quality or significance
Organizing according to the importance of the item or its membership in a specific group type.
This is most visible with groups, such as Supported and unsupported desktops. In the Alphabetical example, the first four would seem out of order if the entire set of desktops were included, as below.
GNOME2
KDE4
LXDE
XFCE4
Awesome
EvilWM
Fluxbox
FVWM
i3
IceWM
Openbox
Spectrwm
WindowLab
Window Maker
Alphabetical
Organizing items by name according to the alphabet.
GNOME2
KDE4
LXDE
XFCE4
Chronological
Placing items in order according to date.
This is distinction primarily relates to historical and archival purposes.
Items are placed in reverse order, most recent first and oldest last.
Ordinal
The items are listed according to number.
Examples are Handbook page and chapter numbers, step-by-step instruction where numbered incremental actions are listed.
Elements are organized from smallest to largest value, or first to last step (similar to logical).

Categories

Membership

Each wiki page (ie, GNOME2) and image page (ie, File:Stub-icon.png) should be a member of at least one category. The wiki page for each category should have a short description to help determine which wiki pages would belong to it.

Format

Place the category link at the bottom of the page, usually contained between the <noinclude> and </noinclude> markers. The first category listed should be the largest group the page belongs to, followed by increasingly specific categories. Handbook pages may be members of multiple categories such as the example below, for the GNOME2 page.

<noinclude>
[[category:handbook]]
[[category:desktops]]
[[category:GNOME2]]
</noinclude>

Images

It is important that the images included in the wiki, especially the handbook portion, be consistent and of a quality that would be acceptable in a professional publication.

Format

  • Strongly recommended to use Portable Network Graphic (png).
  • Limit to a maximum size of 800x600.
  • Use background transparency where things such as irregularly shaped icons or rounded window corners are used.
  • Multiple windows shown as for a single task:
    • Crop to a box that contains both windows with entire window borders intact.
    • Windows may overlap only if necessary details as provided by wiki text are not hidden.
      • Include in the image: options, button labels, window titles, detail that allows the step-by-step to be easily followed without surprises.
  • Single windows:
    • Since multiple window managers and styles are possible, it may be possible to omit the window frame and decoration if such a snapshot may be obtained, otherwise, include the whole window frame and its title bar.
  • Identify each graphic with a Figure number consisting of the section number of the page followed by a letter, alphabetically with 'a' for the first graphic and 'b' for the second and so forth. Directly after the letter, place a colon and a brief description, preferably more concise than its mention within other text on the page.
    • Example: Figure 6.1a: GNOME2 on PC-BSD

Screenshots

  • Dimension: 800x600
  • An initial image of 1024x768 (or 1600x1200 perhaps) can be scaled down to 800x600 without serious distortion.

Capture tips

  • Begin with an unmodified/default desktop configuration.
  • Use 1024x768, 800x600, 1600x1200, or 4:3 dimension ratio.
  • Use a white desktop background to easily capture individual windows or icons.
  • Use Virtualbox with a window larger than the enclosed desktop (desktop will be surrounded with a white frame).
  • The excess white background of cropped images is easily selectable by contiguous shape or color. Next, either invert the selection to cut/copy then paste into a new canvas, or delete the selection so it will be replaced with the alpha transparency.
  • When cropping selections, use the zoom tool to enlarge the work area to prevent loss of details or enable addition of transparency for rounded corners.

Resources

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox