Policies/Wiki Style
From Mandriva
There is a definite need for coherency when a number of people are editing each others documents and this policy outlines the required means of editing this wiki. It will also outline the different templates and styles you can and should use, and when you should use them. It discusses the hierarchy and layout of the wiki, general editing niceties, and other imporant information.
If you want to be considered a valuable resource for maintaining and editing documents on this wiki, and not a nuisance, this page is required reading!
Everyone has their own personal style. We see this how email is written, how spec files are written, and how entries were written in the previous TWiki. We value personal style! Having said that, when it comes to maintaining a set of documents that anyone can write and a lot of people read, consistency makes the wiki look and feel more professional. It will also result in less clutter, less duplicated content, less frustration, and a more pleasant working "experience".
If you are unable, or unwilling, to follow the items noted in this policy, we respectfully ask that you refrain from editing any documents on this wiki.
However, given this wiki is still in the setup process, all elements in the below policy are not written in stone. Discussions to approve and finalize the policy are to happen on the web-discuss mailing list.
Contents |
Altering pages
Summarize your changes
Write a short edit summary in the small field below the edit-box. You may use shorthand to describe your changes, as described in the edit summary legend.
Preview before saving
When you have finished, click Show preview to see how your changes will look before you make them permanent. Repeat the edit/preview process until you are satisfied, then click Save page and your changes will be immediately applied to the article.
Sign your comments on talk pages
On talk pages, please sign your comment by typing four tildes (Tv 11:29, 8 December 2006 (MST)).
You should "sign" your comments on talk pages:
- Three tildes (~~~) give your user name: Karl Wick
- Four tildes (~~~~) give your user name plus date/time: Karl Wick 07:46, 27 November 2005 (UTC)
- Five tildes (~~~~~) give the date/time alone: 07:46, 27 November 2005 (UTC)
Topic Layout
The topic layout, or topical hierarchy, is very important. Everything must be placed into a logical hierarchy that makes sense. Not only does this make things easier to find, but it provides a nice "tree layout" that makes viewing the wiki much easier.
There are a number of "top-level nodes":
- Docs - this node is for end-user documentation
- Policies - this node is for Mandriva policies
- Development - this node is for all things related to development with the noted exception below
- Releases - this node is for Mandriva Linux release information, which includes release notes, errata, and development information particular to that release
- Tools - this node is for the various Mandriva-developed tools
- About - this node is for miscellaneous information about Mandriva as a whole
- Community - community-related information for things such as parties, events, links to other community sites, etc.
- Projects - this node is for Mandriva projects that can encompass many tools, releases. etc. (such as "easier wireless configuration" would be a project where as "drakroam" would be a tool)
- Web - this node is for Mandriva web-related products, projects, and development
These top-level nodes are further broken down into various sub-nodes. For instance, the Releases top-level node logical has the various Mandriva versions below it. So the first sub-node is the name of the product, be it Mandriva, Mandrake, or Corporate. Below that would be the version number, 2007, 3.0, etc. This node would be the "main page" for that release; for example: Releases/Mandriva/2007.
While that sub-node contains short information pertaining to a release, there is far too much information per release to contain it all on one page. To that end, there are more sub-nodes below the release, such as "Errata" and "Notes" and "Development":
- Releases/Mandriva/2007/Errata - this node contains the official errata information
- Releases/Mandriva/2007/Notes - this node contains the release notes for this particular version
- Releases/Mandriva/2007/Development - this node contains development information for this release
We can even go further with the "Development" sub-node, into other nodes such as "Changelog" for a changelog of changes for this version and "codename" or beta/RC name/number for information for a particular release. For instance:
- Releases/Mandriva/2007/Development/RC/Sunna - this node is for the "Sunna" release candidate ("RC") (the node name could just as easily have been "RC2" instead of "Sunna").
It should be evident that there is a logical progression of nodes or leaves that corresponds to it's parent node. In this manner, anyone looking for release information on Mandriva 2007 will know that it can be found in the Releases/Mandriva node and can navigate further from there.
If you're unsure of how the nodes should be created, look at existing content or ask before creating a new node.
Style and Templates
Style and how documents are written are extremely important. Some people use wiki syntax, some people prefer to use HTML syntax. Some people create page names such as "System Administration" while others would use CamelCase or short names such as "SysAdmin" or "SystemAdministration".
Some people will make use of paragraph tags when it's not required, others will use line break tags when there is no need, etc. Some people prefer excessive bolding and italics. These are all things that need to be "normalized" so that the layout and look of content is consistent from page to page.
Templates
MediaWiki allows for the use of templates, which provide consistent styling to text we are trying to mark up or have stand out. Templates are written using:
So to use the title template to bring emphasis to the description or name of the page, use:
The following templates are available and must be used:
- Template:title - the title template is used as the very first element of the page to describe the contents of the page
- Template:version - a template to highlight a version number; this should be used only for Mandriva release version numbers (i.e. Mandriva Linux 2007)
- Template:file - a template to highlight filenames and directory names (i.e. /etc/ssh/sshd_config)
- Template:cmd - a template to highlight a quick command that does not need to be wrapped in <pre> tags, such as urpmi --auto-select; typically used within a paragraph and not standalone
- Template:media - a template to highlight an urpmi medium name that does not need to be wrapped in <pre> tags, such as /main/release; typically used within a paragraph and not standalone
- Template:prog - a template to highlight the name of a program being mentioned (not the name of a program as it's being used, but as it's being referenced); this should only appear once in a paragraph (the first time it's mentioned) (i.e. sshd)
- Template:pkg - a template to highlight an rpm package name (i.e. openssh-server)
- Template:menu - a template to highlight a series of menu clicks (i.e. File->Save)
- Template:var - a template to highlight variable names, like bash or perl, etc. (i.e. $HOME)
- Template:macro - a template to highlight rpm macros and other "%*" constructs in spec files (i.e. %install or %mklibname)
- Template:olang - a template to create a link to similar topics in other languages (see Home and Fr/Maison for an example of how to use this)
- Template:bug - a template to create a quick link to bugzilla with the little bug icon in front of it (i.e. {{bug|12345}} would look like
Bug #12345)
These templates exist to be used and should be used consistently and in the manner noted above. They are used to provide visual queues as to things being discussed and to allow things such as file or package names to stand out, making them easier to distinguish.
Note: If a template has to contain the equal sign (=) or the pipe symbol (|) it won't work unless the "=" or "|" are escaped with the tags <nowiki> and </nowiki>
Style
Here are a few items that should be paid attention to in regards to the style of an edited page:
- There is no need to use paragraph <p> tags; just insert a blank line between paragraphs and the wiki will auto-format; likewise try to avoid <br> tags as well
- Try to avoid using the wikitext notation for bold and italic (''' and '' respectively); instead use the HTML codes (<b> and <i> respectively); using the HTML codes is preferred as it is much easier to see when editing what styling is being applied
- Spacing between header tags is important; there should be exactly 1 blank line preceeding them (the style-sheets help to provide adequate spacing, so extra spaces will only serve to enlarge it too much)
- Do not put links to other pages within a header; links to other pages belong in text, not in headers
- Do not use headers as "highlighters" or for creating a list; headers automatically create a table of contents and should be used to separate logical sections of text, not to create formatted lists
- When linking to another article on the wiki, please do not use the full path of the wiki, but instead use [[Policies/Wiki_Style|Wiki Style]] (instead of, for instance [http://wiki.mandriva.com/Policies/Wiki_Style Wiki Style] as that will keep everything consistent even with domain name changes and so forth
- Please do not use <a href=...> in pages, use the standard [http://foo some text] notation instead
- There should be 1 blank line separating blocks of text; this makes the text easier to read when editing; so please ensure there is 1 blank line between paragraphs, between paragraphs and <pre> tags, lists, etc.
Inter-Wiki Links
You can use Inter-Wiki links to link to other languages on the wiki and to external sites, such as Bugzilla. For instance, using:
[[:bugz:12345]]
Will link to http://qa.mandriva.com/show_bug.cgi?id=12345 automatically. You can pretty this up if you like by using [[:bugz:12345|Bug #12345]] otherwise the link will look like this: bugz:12345. This is using the "bugz" inter-wiki name to represent the Bugzilla url. You can instead opt to use the fancier {{bug|12345}} template instead, however if you want to use your own text but retain the link, it's better to use the inter-wiki link as the bug template gives you no opportunity to create your own link name (i.e. [[:bugz:12345|This was a nasty bug]]).
Where inter-wiki links are available, please use them. This way if a URL ever changes down the road (i.e. bugzilla is no longer available at http://qa.mandriva.com) it's a matter of changing one record in the inter-wiki database table and one template as opposed to potentially hundreds of individual links.
Likewise, the olang template uses the same inter-wiki linking. To link a page to the French version of that page, you would use the olang template with the inter-wiki link inside of it like this:
{{olang|[[:fr:Maison|French]]}}
Here the "fr" inter-wiki name is specifying the french version of the page, called "Maison" in this case. This would take you to /Fr/Maison on the site; ie: fr:Maison. Currently supported language-spaces are:
- de - German
- es - Spanish
- fr - French
- ja - Japanese
- nb - Norwegian
Though it's simpler to just add the l10n interwiki this way:
[[fr:Maison|French]]
which will make mediawiki place them in a special place.
Syntax
Here are some links regarding wiki syntax and the types of things you can do with MediaWiki:
Starting a New Page
Before starting a new page, be sure you have searched carefully first before creating the new page. Chances are, the topic already exists and should be edited, rather than duplicated.
If you need to create a new page, be aware of it's place in the "tree" according to the rules noted in the Topic Layout. If you create a page incorrectly, or create top-level page, someone will either have to delete or move it, which does nothing but frustrate you and create extra work for someone else.
Other good ideas to note can be found on Wikimedia's Starting a new page topic.
Removing or Renaming Pages
Please don't remove or rename pages on your own. If you feel that a page is in a spot where it does not belong, please email the web-discuss-mailinglist with your request and one of the site administrators will perform the page move and/or deletion if it is required.
For the administrators, Wikimedia has some good information:
Talk Pages
Talk pages are an excellent resource. With TWiki, user comments were placed inside the document itself (such as a changelog of who did what, etc). With MediaWiki this is not only not required, but discouraged. User comments on a page detract from the contents of the page itself, making it look dirty and clumsy. Talk pages should be used instead (Talk pages are also known as Discussion pages). These pages can contain a changelog of who made what changes, and they can also contain user comments on the topic, requests for additional information, and so forth. Talk pages are the "drawing board" behind the real content.
Unlike TWiki, there is no need to maintain a "changelog". If, when you are editing a page, you place something in the summary field (i.e. what you did or changed), then anyone viewing the history of the page will not only see your name, but what you put in the summary field (your changelog "entry"), and when you made the change.
Please also refer to Policies/Wiki_Style/Example for an example document that illustrates all of the markup discussed here.
