Policies/Wiki Style

From Mandriva Community Wiki

Jump to: navigation, search
Mandriva Linux Wiki Style Policy

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.

  • Who has time to subscribe to YAML (yet another mailing list). Isn't that the purpose of a Wiki (discussion page [currently almost empty], voting processess if needed etc.)? --nbrouard 09:53, 7 June 2007 (CEST)
  • web-discuss is a ml with very few messages, but writing in the Discussion page is ok. Olivier FAURAX 11:42, 25 August 2007 (CEST)

Contents

[edit] Altering pages

[edit] 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.

[edit] 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.

[edit] 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)

[edit] Flat Layout

On this wiki, there is no hierarchy. This means :

  • The title of a page is its name
  • Avoid using {{title}} as it is not seen as a title by search engine.
  • Use categories and semantic extension to group pages

Don't do :

Title : Releases/Mandriva/2007/Errata
{{title|Mandriva 2007 Errata}}
This is the errata of Mandriva 2007

But :

Title : Mandriva_2007_Errata
[[Category:Errata]][[Category:2007]]
This is the errata of Mandriva 2007

For the title, '_' and ' ' are equivalent. This example can be better with use of the semantic extension : ... of Mandriva [[version:=2007]]... Then, you don't need the 2007 category.

[edit] Title choice

When choosing a title for a new page, please think twice. A title must :

  • be the shortest without ambiguities. Please think how you will link it from other pages (..., please read [[Mandriva Linux 2007 Errata]]....)
  • contains 'Mandriva' + the release number ONLY if specific to the release. Don't use "Virtualization on Mandriva 2007" if it applies to all Mandriva. And then don't use "Virtualization on Mandriva", as it's obvious that this wiki is about Mandriva. "Virtualization" is enough.
  • represent the topic of the whole page

To help, you can think of what you would type in Google to go to this page.

[edit] Good practices

[edit] For search engine

  • don't use '=' to make section titles, start with '==' : when converting to html, Mediawiki will then make h2 instead of h1, making the title of the page the only big title. The table of contents will automatically understand that.
  • for a new page, please make a link from another page of the wiki (if you don't find a suitable one, use your personal page). This make the page discoverable by search engines, but also by other people, who then can use link to it.
  • for a new page, add it to suitable Category from the beginning : this way people will more likely notice there is a new page.

[edit] For readability

  • one topic by article : don't make article about "Graphical programs" on which you deeply explain Gimp, Inkscape, etc. Make one page by program and link to them from the main article. An helper for this is to start by makin the table of contents of the document.
  • try to make one section title or subsection title by screen : it's easier to read when you have "big things" to anchor your vision on.
  • do not attempt to use colors and layout on your own. On this wiki, except a few exceptions such as Home, all the pages must have the same colors and layout (do books have different fonts on each pages ?). If you use a color you want for your text, this could be ugly when changing CSS in the future or lead to unpredictable result (tip : try to use a link in a {{title}} = blue link on a blue background).

[edit] For collaborative effort

  • make links to non-existing pages (... this can be done with [[IPv6]] ..., when the page IPv6 doesn't exist) : this permits to know which pages are missing in Special:Wantedpages.
  • don't hesitate to create a little page with 5 lines : this can be the start for a collaborative page. People are less afraid of improving a page than creating it from scratch.
  • start with the table of contents : you will have to think properly to the topic and, when not finished, people will understand what you wanted to do and can start filling sections
  • don't link to section or subsection : a link to RPM_Tutorial#from_sources will be broken if the section is renamed to RPM_Tutorial#from_upstream_sources

[edit] 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 whereas "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":

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:

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 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.


However, the topical hierarchy has a big downside, making pages titles difficult to read or understand, and unrelated to the document main word it should be indexed with by search engines. Furthermore, it requires a 'title' template so that a readable title is available in the document.

We are going to rewrite this policy document, so that the contents layout is totally flat, hierarchy and structure appearing in categories and semantics usage; the existing topical hierarchy will then likely appear in categories and sub-categories.

Please join the web-discuss mailing-list about that. This is still a work in progress.

[edit] 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.

[edit] 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:

{{template|text}}

So to use the title template to bring emphasis to the description or name of the page, use:

{{title|This is the title of the page}}

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 Image:bug_small.png 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>

[edit] 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.

[edit] 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.

[edit] Syntax

Here are some links regarding wiki syntax and the types of things you can do with MediaWiki:

[edit] 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.

[edit] 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:

[edit] 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.

[edit] Extensions

We are discussing (on wiki-discuss) the inclusion of several extensions that could help:

  • video/media inclusion plugin (Under discussion. Requirements : able to play theora files, videos should be viewable with Mandriva Free edition)
  • At least the following extensions are mandatory for any mediawiki site, CharInsert.php for MediaWiki:Edittools and Expr.php and ParserFunctions for many recent templates needing the #if conditions:
require_once( "extensions/CharInsert.php"); in you LocalSettings.php
require_once( "extensions/Expr.php");
require_once( "extensions/ParserFunctions.php");

You can watch the installed extensions at Special:Version. And they are currently not here 16:49, 14 August 2007 (CEST).

Retrieved from "http://wiki.mandriva.com/en/Policies/Wiki_Style"
Personal tools