WikiGuide

Differences between revisions 27 and 32 (spanning 5 versions)
Revision 27 as of 2006-03-26 07:45:38
Size: 5913
Editor: S0106000d88b9f3db
Comment: couple of minor style points
Revision 32 as of 2006-05-09 03:36:27
Size: 5630
Editor: user-1121a25
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
This page contains some guidelines and help for how to post and work on the documentation in the Ubuntu wiki (UserDocumentation). Our aim is to make consistent, integrated and reliable documentation that users can access simply and quickly.

Contents of this page:

[[TableOfContents(2)]]
||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;">'''Contents'''[[BR]][[TableOfContents]]||
'''Below are some guidelines and help for how to post and work on the documentation in the Ubuntu Wiki (UserDocumentation). Our aim is to produce consistent, integrated and reliable documentation that users can access simply and quickly.'''
Line 9: Line 6:
Our aim is to make documentation which a new computer user can understand and which teaches the user what they are doing. With that in mind, please take into account the following guidelines: Our aim is to make documentation which a new user can easily understand and follow. With this in mind, please take into account the following suggested guidelines:
Line 11: Line 8:
 * Always search for existing guides when inserting material. Adding new pages where there is already a document in existence causes immense confusion for users who don't know what to trust! This will mean that your work will cause more harm than good. If the existing document is very bad, out of date, or missing something, improve it!!
 * Please read AND understand the [http://doc.ubuntu.com/styleguide/styleguide.html Documentation Team Styleguide] before posting.
    * A few minor style points
:
        * When referring to Ubuntu releases, use "Ubuntu X.XX (Nickname)" or just "Ubuntu X.XX" - so "Ubuntu 5.10 (Breezy Badger)" or "Ubuntu 5.10", rather than just "Breezy" or "Ubuntu Breezy".
        * Capitalize the names of the Universe & Multiverse repositories when you use them. Also, Linux, Ubuntu, Windows, etc should be capitalized.
 * Always leave a comment when saving your edits so others can see what you are doing easily when reviewing RecentChanges.
 * Use the ["forum"] page when adding material from the forum that is not fully formatted or has not been reviewed.
 * If you create a new page, please use as descriptive a name as possibl
e - the default search in this wiki is by page title, not full text.
    * If you create a page with "Howto" in the title, please put it at the end of the title, for example PocketPCHowto rather than HowtoPocketPC. Not only is this the existing style used, the Category pages sort alphabetically, so putting it at the end means more sensible sorting.
 * Search for existing guides before creating new pages. If an existing document is of poor standard, out of date, or missing something, improve it!!
 * Attempt to abide by the [http://doc.ubuntu.com/styleguide/styleguide.html Documentation Team Styleguide] before posting, in particular:
    * When referring to Ubuntu releases, use "Ubuntu X.XX (Nickname)" or just "Ubuntu X.XX" - eg. "Ubuntu 5.10 (Breezy Badger)" or "Ubuntu 5.10", rather than just "Breezy" or "Ubuntu Breezy".
    * Capitalize the names of the Universe & Multiverse repositories when you use them. Also, Linux, Ubuntu, Windows, etc should be capitalized.
 * Leave a comment when saving your edits so others can see what you are doing when reviewing RecentChanges.
 * If you create a new page, use a descriptive name - the default search in this wiki is by page title, not full text.
    * If you create a page with "Howto" in the title, please put it at the end of the title, for example PocketPCHowto rather than HowtoPocketPC. Placing "Howto" at the end of the title is the existing style used and it aids in sorting documents on Category pages.
Line 21: Line 16:
 * Don't link pages on the pages directly linked-off UserDocumentation (eg. [:Multimedia]) until they have been reviewed and are out of CategoryCleanup  * Do not link pages on the pages directly linked-off UserDocumentation (eg. [:Multimedia]) until they have been reviewed and are out of CategoryCleanup
Line 37: Line 32:
 * To make a list you use a white space at the beginning of a line, followed by either an asterisk (for bullet points), a number, letter etc.
 * To make a heading you use {{{= Title =}}} for a level one heading, {{{== Title ==}}} for a level 2 heading, and so on.
 * To make a list, use a white space at the beginning of a line, followed by either an asterisk (for bullet points), a number, letter etc.
 * To make a heading, use {{{= Title =}}} for a level one heading, {{{== Title ==}}} for a level 2 heading, and so on.
Line 70: Line 65:
 * Inserting a table of contents - use: {{{[[TableOfContents]]}}})
   * To ge
t the right-hand floating ToC like UserDocumentation (and other pages) have, use:
{{{
 * Inserting a table of contents such as what you see at the top of this page:
{{{
Line 75: Line 69:
 * To insert a simple table of contents, without the box around it, just use: {{{[[TableOfContents]]}}})

Below are some guidelines and help for how to post and work on the documentation in the Ubuntu Wiki (UserDocumentation). Our aim is to produce consistent, integrated and reliable documentation that users can access simply and quickly.

Style and Guidelines

Our aim is to make documentation which a new user can easily understand and follow. With this in mind, please take into account the following suggested guidelines:

  • Search for existing guides before creating new pages. If an existing document is of poor standard, out of date, or missing something, improve it!!
  • Attempt to abide by the [http://doc.ubuntu.com/styleguide/styleguide.html Documentation Team Styleguide] before posting, in particular:

    • When referring to Ubuntu releases, use "Ubuntu X.XX (Nickname)" or just "Ubuntu X.XX" - eg. "Ubuntu 5.10 (Breezy Badger)" or "Ubuntu 5.10", rather than just "Breezy" or "Ubuntu Breezy".
    • Capitalize the names of the Universe & Multiverse repositories when you use them. Also, Linux, Ubuntu, Windows, etc should be capitalized.

  • Leave a comment when saving your edits so others can see what you are doing when reviewing RecentChanges.

  • If you create a new page, use a descriptive name - the default search in this wiki is by page title, not full text.
    • If you create a page with "Howto" in the title, please put it at the end of the title, for example PocketPCHowto rather than HowtoPocketPC. Placing "Howto" at the end of the title is the existing style used and it aids in sorting documents on Category pages.
  • Put pages into CategoryCleanup when they have not been reviewed and be encouraged to discuss your contributions on the [http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc docteam mailing list]. If you let us know about it, it can be reviewed more quickly and taken out of CategoryCleanup.

  • Do not link pages on the pages directly linked-off UserDocumentation (eg. [:Multimedia]) until they have been reviewed and are out of CategoryCleanup

Deleting and Renaming

Deleting and/or renaming pages causes major problems: it breaks links within the wiki itself and also on the internet and people's bookmarks. So the number one rule is don't delete or rename pages unless you really know what you're doing. Having said that, here are a couple of guides to help:

  • A good alternative to renaming is to insert a redirect from the target page to the original page. See HelpOnProcessingInstructions

  • You can search for all of the pages which contain a link to a specific page by clicking on the title of the specific page. If you rename or delete a page, you MUST fix all these links.

  • If you are thinking about renaming a well-known or useful page, please raise it on the DocumentationTeam [http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc mailing list].

Help on Editing

The wiki can often seem like a scary thing to start editing, but this is in fact NOT the case! It is easy to start editing and contribute. The best way to start is to look at the formatting which is employed on various pages, (for example, you can see the code of this page [https://wiki.ubuntu.com/WikiGuide?action=raw here].)

The basic rules are:

  • To create a page, type the address for the new page into the address bar of your browser and then select "Create new page". Alternatively, make a link for your page in an existing page, save it, click on the new link, and select "Create new page".
  • Paragraphs should be separated by a blank line.
  • To make a list, use a white space at the beginning of a line, followed by either an asterisk (for bullet points), a number, letter etc.
  • To make a heading, use = Title = for a level one heading, == Title == for a level 2 heading, and so on.

  • Placing '' around words or phrases will make them italics, and ''' will make them bold.

  • To quote a block of code, wrap paragraphs in  {{{  }}}.

An Example Page:

= Title of Page =
== Subtitle ==
This page is going to explain how to write a guide on the wiki. The following things are important:
 * Read the docteam Styleguide
 * Make sure you are not reproducing material already on the wiki
 * ask the Documentation Team to check the guide afterwards and place it in CategoryCleanup

The following paragraph is a lettered list:
 a. this is the ''first'' item
 a. this is the ''second'' item
 a. this is the ''third'' item
{{{
this is a block of code
} }} (the space should not be in your version)

It is that easy!

For more help about this wiki, see the page HelpContents

Clever Things

As you edit the wiki you will learn how to use the power of the wiki software to do even more clever things! Here are some examples:

  • To see almost all the wiki's formatting in action, have a look at the SyntaxReference page.

  • Inserting Icons - see IconsPage

  • Inserting a table of contents such as what you see at the top of this page:
    • ||<tablestyle="float:right; font-size: 0.9em; width:40%; background:#F1F1ED; margin: 0 0 1em 1em;" style="padding:0.5em;">'''Contents'''[[BR]][[TableOfContents]]||
  • To insert a simple table of contents, without the box around it, just use: [[TableOfContents]])

Please feel free to discuss the contents of this page on the DocumentationTeam [http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc mailing list].


CategoryDocumentation

WikiGuide (last edited 2008-08-06 16:40:22 by localhost)