Difference between revisions of "PC-BSD Wiki:Style Guidelines"
Tigersharke (Talk | contribs) (→Commandline examples) |
Tigersharke (Talk | contribs) (→Commandline examples) |
||
| (3 intermediate revisions by one user not shown) | |||
| Line 114: | Line 114: | ||
Cause a box to enclose the text by starting the sentence with a space, however this has a small problem with keeping the text inside the box. For whatever reason, the text extends out of the dashed lines of this box, to the right. | Cause a box to enclose the text by starting the sentence with a space, however this has a small problem with keeping the text inside the box. For whatever reason, the text extends out of the dashed lines of this box, to the right. | ||
| − | ; '' | + | |
| + | ; ''The replacement template: txtbox''. | ||
| + | {{txtbox|box= | ||
| + | A much improved variation of that above 'standard' also encloses the text within a similar box. Even though the text is a short paragraph of four sentences in length, it does not have the same flaw as before. The text is neatly contained within the dashed lines of the box, and also does not require the initial space character at the start of the first sentence. If that character were included, it would display with two nested boxes. | ||
| + | | | ||
| + | Text to the right of the box is also possible. This is the [[template:txtbox|''txtbox'' template]] and works much the same as the next template, except for its appearance. | ||
| + | }} | ||
| + | |||
| + | |||
| + | ; ''Optional template for special situations: cli'' | ||
{{cli|xterm= | {{cli|xterm= | ||
This is an example of such content.<br> | This is an example of such content.<br> | ||
| Line 124: | Line 133: | ||
}} | }} | ||
| − | + | === Tables === | |
| − | + | Presently various templates are needed to more easily result in a table with the appearance below. However, in the near future there will be an addition of a class="spiffy_table" which will further simplify, and at that time the templates can be modified to include it transparently. | |
| − | + | ||
| − | + | {{Tbl-init}} | |
| − | + | ||
| − | }} | + | |
=== Trademarks === | === Trademarks === | ||
Revision as of 12:29, 7 February 2013
| PC-BSD® Wiki:Style Guidelines |
Contents |
Objective
The purpose of defining how pages on the wiki should be created, is to help maintain consistency by having a set standard or model to follow, 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 incomplete or not yet defined, 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
- aren't use are not,
- can't use can not,
- cannot use can not,
- doesn't use does not
- don't use do not,
- hasn't use has not
- haven't use have not
- weren't use were not,
- won't use will not,
- you'll use you will,
- you'd use you would,
- you're use you are
- you've use you have.
- 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.
- Dates
- Given that some date formats can be problematic: (07-03-2012) Does the author mean July 3rd 2012, or March 7th 2012. The wiki offers a per-user preference for date format. This also formalizes instances of dates which may also aid translations.
- {{#dateformat:01 May 2012}} should be used resulting in 01 May 2012 which conforms to each user's preferences.
- Uncapped proper names
- Some software is officially named in lowercase, yet sentences should usually begin with a capital letter. The solution is to avoid using those special proper names as the word that begins a sentence.
Hypertext Links
Within the text, it is helpful to add a link to topics, pages, and sites to further explain and allow for additional research.
- Link name
- Use a descriptive word or phrase. It can be the general location (page/site) of the link, as long as the link itself is to the specific section (when ever possible). Try not to be too general/generic. Highlight and italic used for clarity in the examples.
- Replace this: You can find more information about hardware compatibility here.[1]
- With this: You can find more information about hardware compatibility on the FreeBSD hardware forum[1].
- Replace this: This forum post[1] explains how to properly plug the outlet tube of an inlet drain line.
- With this: This PlumberCraft forum post[1] explains how to properly plug the outlet tube of an inlet drain line.
- URL
- Use an ending slash with any url that leads to a directory or non-file (such as any site name). It is prudent to verify that an adjusted link is valid since some sites do not use extensions for file names. This convention will aid with consistency and help to eliminate technically different but effectively identical URLs.
- This is a valid url: http://forums.freebsd.org
- Url with proper syntax on this wiki: http://forums.freebsd.org/
- Example of a url that ends with a file name: http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/sound-setup.html
- 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. If the link text is to be bold or italic or both then the modifier characters must be directly around the alternate text and not around the entire citelink phrase below.
- For the link use {{Citelink|url=complete URL|txt=alternate text}}
- Also place a total of exactly one <noinclude>{{refheading}}</noinclude> 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.
- Valid markup is [[wikipedia:page name]] or [[wikipedia:page name|alternate text]] except in the context of the handbook itself.
- For the link use {{Citelink|shortcut|url=page URL|txt=alternate text}}
- Current shortcuts we have defined locally can be found at (or carefully added to) OurInterwiki.
- For the link use {{Citelink|shortcut|url=page URL|txt=alternate text}}
- Also place a total of exactly one <noinclude>{{refheading}}</noinclude> at the bottom of the page, above the category links section.
Special Characters
- Traversal of menus or windows
- use an arrow (➜)
- Replace this: PC-BSD control panel -> System manager -> System packages tab
- With this: Control Panel ➜ System Manager ➜ System Packages
- This is a unicode UTF-8 character but may appear gibberish in other charsets such as IS0 8859-1.
Describing buttons and other named visual objects
Often the documentation within the handbook will describe a series of steps that includes clicking upon a button. In other places, the handbook may indicate the name of a window or folder or other object on the screen.
- These items could be further emphasized, but their names must be within quotes.
- Example: Click on the "Submit" button along the lower edge of the "Compose response" window.
Commandline examples
Frequently in the handbook we provide a series of commands or shell output. Standard method should be replaced with the template:txtbox.
- The standard method
Cause a box to enclose the text by starting the sentence with a space, however this has a small problem with keeping the text inside the box. For whatever reason, the text extends out of the dashed lines of this box, to the right.
- The replacement template: txtbox.
| A much improved variation of that above 'standard' also encloses the text within a similar box. Even though the text is a short paragraph of four sentences in length, it does not have the same flaw as before. The text is neatly contained within the dashed lines of the box, and also does not require the initial space character at the start of the first sentence. If that character were included, it would display with two nested boxes. |
- Optional template for special situations: cli
|
Xterm | 
|
||
|
This is an example of such content.
|
It is provided by the Cli template | |||
Tables
Presently various templates are needed to more easily result in a table with the appearance below. However, in the near future there will be an addition of a class="spiffy_table" which will further simplify, and at that time the templates can be modified to include it transparently.
|
Capture tips
- Begin with an unmodified/default desktop configuration- including only the installed software to be discussed.
- Emphatically recommended to use Virtual Box with a desktop of 4:3 ratio, Host name: Demo System, Username: PC-BSD_User, which would allow for consistency, universality, and genericness.
- Use a white desktop background to easily capture individual windows or icons.
- Expand the Virtualbox window to be 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.
- Where possible, resize windows so that their entire content can be shown without scrollbars.
Administrative
Categories
All pages that use templates: SwapTitle, NavHome, and NavHeader, are automatically added to a category of their pagename (or custompagename where one is defined).
- Membership
- Each wiki page (ie, GNOME2) and image page (ie, File:Stub-icon.png) should be a member of at least one category.
- The category chosen may be determined by the description given on the individual category pages.
- 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. Category names should be capitalized the same as the pages involved, or each individual word has its first letter capitalized. Some templates can auto-categorize pages into their page title category.
- <noinclude>
- [[category:Handbook]]
- [[category:Desktops]]
- [[category:GNOME2]]
- </noinclude>
- <noinclude>
- Description
- The categories themselves should have some sort of explanation to guide their use.
Page structure
- Header
- Each handbook page contains a 3-icon navigation panel across the top, while other pages linked from the main page contain a simplified version.
- Stubs
- With relation to new pages that have minimal content, a stub warning is included to enhance visibility and aid with community involvement.
- Comments
- Used in locations of the wiki markup that purposely and specifically do not follow the guideline, or places where reminders or explanations are needed or useful.
- <!-- comment text -->
Headings
Generally, the headings on a page help to outline and organize the content. It should also be noted that having identical headings or sub-headings within the entire wiki can cause trouble with future editing or navigation, and should be avoided. Include an action word or phrase or otherwise differentiate between the two locations, even if they are discussing the same content, the purpose in each case is not likely identical. (If a certain heading style is preferred though it does not match the guide below, then perhaps adjustments to the wiki site css need to be made.)
Page title= Page title = Level 2== Level 2 == Level 3=== Level 3 === Level 4==== Sub-heading ==== Level 5===== Level 5 =====
Level 6====== Level 6 ====== |
Resources
- Wikimatrix for mediawiki
- The preliminary PC-BSD wiki stub example page.
- Manual of Style
- Wikipedia:Manual of Style
References
