Differences between revisions 83 and 84
Revision 83 as of 2008-07-25 19:37:34
Size: 24736
Editor: JustinBRye
Comment: third try getting to the end of (8)
Revision 84 as of 2008-07-28 13:25:53
Size: 24932
Editor: JustinBRye
Comment: to end of (9)
Deletions are marked like this. Additions are marked like this.
Line 117: Line 117:
## FIXME (JustinBRye editing sweep, I'll come back to them) ## FIXME (JustinBRye editing sweep, 2008/08, I'll come back to them)
Line 125: Line 125:
## Rename the sections more coherently (does this mean searching the wiki for these anchornames?) ## FIXME: Rename the sections more coherently (does this mean searching the wiki for these anchornames?)
Line 227: Line 227:
## FIXME: this isn't much of an explanation... but it _is_ a genuine call for the page to be deleted! ## FIXME: this isn't much of an explanation...
Line 232: Line 232:
CategoryProposedDeletion Category``Proposed``Deletion
Line 259: Line 259:
 * Is a new page really needed? Might it already exist under a different name? Could the content be added to an existing page ?  * Is a new page really needed? Might it already exist under a different name? Could the content be added to an existing page?
Line 262: Line 262:
if you decide to proceed: If you decide to proceed:
Line 359: Line 359:
Line 372: Line 371:
[[Anchor(link-to-translations)]]
The top of each page shows links to the same page in other languages - see [#article-header Headers], and DefaultTemplate as an example.
Line 373: Line 375:

__The principles: __
 * All pages are named in English. The "master" page is always the English one. ~-( We must choose one "master" language. see "synchronize" below)-~
 * This page is called ''Referent Page''. When you modify a translated page, you must update or notify the referent page
 * Translated page is named like "[http://www.debian.org/international/l10n/po/ Language]" + "/"+ "!NameOfReferentPage"
  * Example:
   * Referent page: ["Hardware"]
   * French page: ["fr/Hardware"]
 * One should attempt to keep the same layout in every languages ~-(1. it's easier to synchronize pages 2. some update might have to be made by people that don't speak your language : update link ; comment-out obsolete/inaccurate paragraphs, etc.) -~
 * If the page doesn't exists in English, create it too. If you don't feel comfortable writing in English, just create a page with the usual headers and link to your translated page. (make sure you tag your page with UpdateEnglish).
 * If the page doesn't exist in ''Language'' :
  1. copy paste English version in it.
  1. update the page header to match Translated page one.
  1. see synchronize contents.
## FIXME: Can I really create /en_SE/JustinBRye?
## Also, what happens in cases like "fr/Free" when one language needs d12n and the other doesn't?
The principles:
 * Any topic given a wiki page may have many translations, but there is always one "base" page.
 * Since this master copy has to be in some language, we standardize on using the US English version.
 * Translated pages use the naming scheme "[http://www.debian.org/international/l10n/po/ languagecode]" + "/" + "!EnglishName" - for example:
  * Base version: ["Hardware"]
  * French translation: ["fr/Hardware"]
 * When you modify a translated page, update or notify the English version too.
 * Try to keep the layout the same in every language, since it simplifies synchronization (especially, editors who aren't fluent in your language will still have some chance of finding and updating the right element).
 * If the page doesn't exist in English, create that too. If you don't feel comfortable writing in English, just create a page with the usual headers and link to your translated page, making sure you tag your page with Update``English.
 * If the page doesn't exist in your language, start by copy/pasting it from the English version and updating the page header to match the page name, then see below.
Line 389: Line 389:
== Synchronize contents ==
Some recommendations :
 * All the versions of a page should keep the same layout (paragraphs in the same order, disposition, etc.)
 * When you update a page according to a page in another language (i.e synchronizing pages), try updating the whole page at once, then change the matching "revision" number in the header.
  * If you can't update the synchronization of the whole page at once, add a comment like {{{## TRANSLATION UPDATE STOPPED here}}} where you stop.

 * If the translated page if more recent than the English one :
   1. Update The English version yourself if you can (don't be afraid to make mistake someone would correct them).
   2. Or tag the page with "UpdateEnglish" (at the bottom), and add "+ IMPROVEMENTS" to the ''English revision'' comment.
 * If the English page if more recent than the translated one :

[[Anchor(link-to-translations)]]
remember: Links to the same page, in other language, are included at the top of the pages. see [#banner header] and DefaultTemplate as example.
== Synchronizing translations ==
When you're updating a page to match one in another language (i.e "synchronizing" the versions),
 * All versions of a page should keep the same layout (formatting, paragraph order, etc.).
 * Keep the revision status of the page clear:
  * (either) update the whole page at once, and then change the matching "revision" number in the header
  * (or) add a comment like {{{## TRANSLATION UPDATE STOPPED here}}} where you stop.
 * If the translated page is newer than the English one:
  * (either) update the English version yourself if you can (don't worry about minor language errors - someone will correct them)
  * (or) append an "Update``English" tag at the bottom of the page, and add "+ IMPROVEMENTS" to the ''English revision'' comment.
## FIXME: What's all this about revision-number headers? What does it mean by "the _English revision_ comment"?
Line 405: Line 402:
People involved in translating Debian Wiki pages can (should) add !CategoryWikiTranslator at the end of their homepage.

 * The list of translators :
["CategoryWikiTranslator"]
People involved in translating Debian Wiki pages should add the tag ["CategoryWikiTranslator"] on their homepage.
Line 446: Line 440:
## FIXME: Q) why is this generic FAQ hidden away at the end of the EditorGuide?
## A) because the purpose of wikis is to lose documentation

Translation(s): [:fr/DebianWiki/EditorGuide:Français]

(!) [:DebianWiki/ConventionsDiscussion:Discussion]


This page provides instructions for people wanting to edit the content of wiki.debian.org.

There's a [:DebianWiki/EditorQuickStart:?QuickStart] for new editors.

For generic help on formatting under moinmoin wiki, read moinmoin's ["HelpContents"] pages (in the sidebar). ["?SyntaxReference"] is handy. You can experiment in ["WikiSandBox"].

If you disagree with any statement below, comment it out, then start a new discussion thread in the [:DebianWiki/ConventionsDiscussion:discussion] page.

  • ?TableOfContents(2)

?Anchor(account)

Your Account

  • Your wiki username should be in the format "FirstnameLastname" ("IrcNickname" or your debian developer login are fine too).

  • Adjust the timezone in your ["?UserPreferences"] page.

Your WikiHomePage

You can use the HomepageTemplate when you create your homepage. Here are ideas for content, grabbed from various existing homepages.

  • Your full name.
  • Your main homepage outside this wiki.
  • Your email address.
  • Your location (city and country) useful for timezone considerations and more

  • If you use IRC, your usual server, channel and nickname
  • If you are a Debian Developer (DD), your login name (with a link to http://qa.debian.org/developer.php?login=foobar@debian.org).

  • Non-DDs can link to [http://bugs.debian.org/from:foo@bar.com].

  • Your subjects of interest (not limited to Debian).
  • Your ToDo/Done list.

  • (Some of) Your contributions to open source (bug reporting; writing/translating; developing/maintaining...)

Make sure you keep the CategoryHomepage tag at the bottom of your homepage (present in the default HomepageTemplate).

Subscribe to pages

  • You could subscribe to the pages relevant to your subjects of interest.

?Anchor(lost-password)

Lost Password

If you lose your wiki.debian.org password, go to to the page ["?UserPreferences"], then follow the instructions there (type your email address, then click on ?GetText(Mail me my account data)).

?Anchor(writing-style)

Writing Style / WikiEtiquette

There are at least five major styles of Wiki page

Elements of good style for each type are explained further on their individual pages.

Try to maintain balance when writing. This includes visual balance, but also an attempt to avoid bias. If you find that your comments are controversial, sign them, so that others will feel more free to disagree publicly.

  • Don't make EveryThing into a UselessWikiName. Knowing when to make a new page is one of the hardest parts of WikiStyle.

  • RefactorMercilessly There is no page in the WikiUniverse that is finished. All content can be refined. See RefactoringWikiPages for many useful thoughts.

  • If the wiki topic is fairly long then it would be good style to give a quick overview of what has been discussed in the topic as a sort of concluding paragraph. If a concluding paragraph cannot be easily written then perhaps the scoping of the topic was not right, and it should either be separated into subtopics or merged with others into one larger topic. This is common when ThreadMode meanders off topic.

See also: this GoodStyle page.

?Anchor(links)

Links

Don't overuse linking. If there are too many, the reader won't know which links are useful. You can move some of the links to a [#footer "See also"] section at the bottom of your page (but again, not too many).

Where links point to a page in another language, append "(in $language)", thus: [:fr/QuelqueChose:SomethingInFrench] (in French)

See also moinmoin's ["HelpOnLinking"]

?Anchor(internal-links)

Internal Links (within this wiki)

  1. ["FooPage"] is usually the preferred syntax.

  2. [:SomeParentPagewith/FooPage:FooPage] is frequently used to shorten subpages.

  3. [:EditorGuide:editor guide] can be used to help fit the link name into a sentence as normal lower-case words.

  4. Don't "rename" the link by using [:PageName:Another title] (if you have to do this, it implies the page is misnamed).

In all cases, make sure that the link label is meaningful to visitors, and that the link doesn't lead somewhere unexpected (preferably, the link label should be the same as the page title).

To link within a page, you should define the target anchor using [[Anchor(bar)]] (see ["HelpOnMacros"]), then use [#bar Bar Chapter] or [:Foo#bar:Bar Chapter] (where Bar Chapter is the actual paragraph title).

?Anchor(links-to-www)

The preferred way to link to external resources is:

(Avoid the notation  [http://www.foo.com link label] , which hides the target URL, unless the context makes it clear, as in "John Doe provides a script named [http://www.johndoe.org/test.sh test.sh].")

  • Group external links in the last section of the page.
  • Call this section External links.

  • Any "project homepage" link can go in this section, or (if there are no other external links) a See also section.

Use ["InterWiki"] format to link to Debian packages, bugs, RFCs and Wikipedia articles.

?Anchor(links-from-www)

If an (important) page is linked from outside Debian, it's a good idea to tag it with CategoryPermalink, so that nobody removes it inadvertently.

?Anchor(formatting)

Formatting

?Anchor(article-header)

  • Add links to translated versions (make sure they really exist!):

    Translation(s): [:de/DebianWiki/EditorGuide:Deutsch] - [:fr/DebianWiki/EditorGuide:Français]

  • For sensitive pages, insert a Discussion link: (!) [:/Discussion:Discussion]

  • Compare DefaultTemplate

?Anchor(footer)

  • Footer is optional
  • Insert [#categories Categories] for relational structure
  • Insert a section like "See also" for links
  • Compare DefaultTemplate

?Anchor(disambiguation)

Disambiguation header

Sometimes, a page's name can be ambiguous. If this can't be avoided, you can insert something like this at the top of the page:

Disambiguation : This page is about Debian Conferences.?BR For Debian configuration management system, see ["debconf"].

  • Sample:

    ||<tablestyle="width:65%;margin-left:35%;padding-left:30pt" style="border:1pt solid #b48;border-left:5pt solid #d4a">'''Disambiguation :''' This page is about ''Debian Conferences''.[[BR]] For ''Debian configuration management system'', see ["debconf"].||

?Anchor(official)

Debian "official material" header

Often, the content of a Debian wiki page is also covered by some piece of "official" Debian Documentation (or in some other "reference" location). The wiki page can still be useful for collaboration. It's a good idea to add a link to the reference location at the top of the page.

Sample link presentation to some official page, related to the current subject.

inline:Portal/IDB/official-doc.png

http://www.debian.org/somewhere - Sample topic

  • Sample:

    ||<tablestyle="width:100%;" style="width:32px;border-color:#ff9ec2" >inline:Portal/IDB/official-doc.png||<style="border-color:#ff9ec2;background-color:#ffe4f1" >http://www.debian.org/somewhere - Sample topic||

    ToDo: The image should be moved to moinmoin's static-content folder. It would be nice to use CSS stylesheet and Class too.

FAQ sections

A typical FAQ section could be formatted like this:

Q. How do I do XXXX?
A1) You can do XXXX by doing X.
A2) You can do XXXX by doing Y.

Sample (notice the space at the beginning of the lines):

 Q. How do I do XXXX? :: A1) You can do XXXX by doing X.
 :: A2) You can do XXXX by doing Y.

Table of Contents sections

If a page gets long, you might want to add a Table of Contents. See the example at the top of this page!

  • Sample (note how the table is indented with one space):

     [[TableOfContents(2)]]

Page Fragments

Not only code can be be reused - page content can too! If you notice that a given paragraph has to be repeated on many pages, you can reuse ("include") a page fragment each time. (Do not abuse this to duplicate content everywhere!)

  • A page meant to be included in another should be named */!PageFragment/*
  • Add a comment ## at the top of the page so people understand why it's "incomplete" (a fragment!)

  • See the [[Include()]] macro in ["HelpOnMacros"]

A sample is available at ["InstallingDebianOn"] and ["InstallingDebianOn/PageFragments/Philosophy"]. Also note how the page is included inside a table (but don't use this hack to bypass moinmoin formatting limitations: see [#complex-formatting Complex Formatting]).

?Anchor(complex-formatting)

Advanced Formatting/Complex Formatting

AVOID using "advanced" formatting (using tables, include, etc.)

  • It's difficult to understand and maintain for you and other wiki editors.
  • It's difficult to read the diff of complex formatting.

  • The GUI editor may break your layout.

?Anchor(images)

Images, media and attachments

See also: moinmoin's ["HelpOnLinking"].

?Anchor(attachments-credits)

Add credits and copyright information at the bottom of the page where you attach an image, typically :

## attachments:
##  openlogo-100.jpg  Copyright 1999 "Software in the Public Interest" from http://www.debian.org/logos/openlogo-100.jpg

Attachment location

It's often a good idea to attach the image to the parent page (in case the image is reused in other subpages).

For translated pages, attach the image to the English version (internationalized/localized images should be attached to the internationalized/localized pages).

?Anchor(tags)

Tagging "Work needed"

These tags are meant for wiki editors, not for visitors, so don't make them too intrusive; instead of putting a warning tag at the top of the page, insert it in the page's [#footer footer].

Using categories

  • CategoryProposedDeletion 

CategoryProposedDeletion

Using tags

?Include(WikiTag)

Note: do not use the [http://moinmo.in/HelpOnProcessingInstructions #deprecated] processing instruction, as it prevents further editing of the page (e.g. to fix broken links). If you need to mark a page as needing to be improved/removed, use an appropriate ["WikiTag"] instead.

?Anchor(pages)

Pages

?Anchor(pages-name)

URL/page naming conventions

  • Use only CamelCase formatting (as opposed to Underscore_Separated).

  • The first letter of the first word should be upper case.
  • Special characters should be avoided in page names.
  • Slashes function to create (directory-style) groups of related subpages. If your page clearly belongs to a collection, you might consider creating it as a subpage - see for example the Moinmoin documentation [:HelpOnEditing/SubPages:?SubPages].

  • For translated pages, see [#translation Translation section].
  • Picking an appropriate name is important. It should clearly state what the page is about and should contain the word visitors will search for.
  • Avoid ambiguous names - don't use, for instance:
    • "About"... about what? About the Debian OS, community, wiki...?
    • "Release"... does it mean previous releases, the current stable release, the release life-cycle, future release status, release process, release team, etc...

?Anchor(create)

Creating a page

Before you create a page, ask yourself some questions:

  • Is a new page really needed? Might it already exist under a different name? Could the content be added to an existing page?
  • Does it comply with the wiki.debian.org [:DebianWiki/Content:Content guidelines]?

If you decide to proceed:

  • Choose a name for a page - see [#pages-name URL/page naming conventions].
  • Search for an appropriate portal page on the CategoryPortal page (you may find more than one; choose the best)

  • Create a link to your new page in this portal, then click on it.
  • Pick the appropriate template (DefaultTemplate is recommended)

  • If your page relates to a subject already covered by some official Debian documentation, link to it at the top (see [#official Debian official material])
  • Once the page is complete, make links to it from relevant pages (one link is often enough).
  • More hints:
    • Re-read it two days later (does it still look good?)
    • Subscribe to that page.
    • This page isn't "yours", so don't be offended when other people "improve" it.

See also: moinmoin's ["HelpOnPageCreation"].

?Anchor(rename)

Renaming a page

Cool URIs don't change ([http://www.w3.org/Provider/Style/URI w3]). Still, sometime it's a good idea to rename a page when its name don't accurately describe the page content.

Before you rename a page:

  • Use Google (or equivalent) to check whether the page is linked from outside this wiki. Search link:wiki.debian.org/FooBar. If it is referenced, think twice before renaming the page. If you rename the page, consider creating a [#redirect-page redirect] page and contacting the owner of the referring page to get the links updated.

  • Check if this page is linked from inside this wiki (open the page and click on the title to get the list of back links).

If you decide to actually rename the page:

  • Choose a name for a page. see [#pages-name URL/page naming conventions].
  • Make sure you update all the pages that used to point to the old name (type the previous page name into the search bar, then click "Text"!).
  • Also take care of translated versions of the page.

Note: If the page-rename seems to require a "redirect" page, that might mean that the page shouldn't be renamed!

?Anchor(delete)

Deleting a page

Read the [#rename Renaming a page] hints, since they apply here too.

If you think a page should be removed, you can either:

  • Delete the page yourself (writing your rationale in the comment field).
  • or Tag the page with "CategoryProposedDeletion" so other editors can react (i.e. put the tag and explanation at the bottom of the page).

Don't be rude: do not copy-paste the content of an existing page into a new one, and delete the old page - this loses page history. Instead see [#merge-and-split Merging and splitting pages].

Again, if there are translated versions, deal with them too!

?Anchor(merge-and-split)

Merging and splitting pages

Reorganising pages is a good idea. You are encouraged to:

  • Merge "duplicate" pages covering the same subject.
  • Merge similar page, if both are "too short".
  • Split long pages that cover more than one topic (but consider adding a [[TableOfContents]] instead.). Remember: too many empty pages are just boring for visitors.

Try to preserve page history:

  • Use the Comment field to record the "before" and "after" page-names in splits or mergers.
  • Merge pages into one of the existing pages, not into a newly created page.

For translations: if you can't merge/split translated pages, add directions (comments) in the translated version so translators can keep up!

?Anchor(redirect-page)

Redirect pages

On some occasions, you might want to create a "redirect" page (which automatically redirects the browser to the proper page).

Don't over-use this tool.

sample :

#redirect DestinationPage
go to ["DestinationPage"]

Note that #refresh isn't enabled on this wiki.

See also: moinmoin's ["HelpOnProcessingInstructions"].

?Anchor(categories)

Categories

moinmoin wiki's help: [:HelpOnCategories:using categories].

The list of categories used on this wiki: ["CategoryCategory"].

?Anchor(portal)

Portals

Portals are hub pages containing links to articles. They complement the relational structure offered by CategoryCategory, and the [:FindPage:integrated search engine].

Portal pages should be based on PortalTemplate.

Do not use Edit(GUI) since it will break some wiki contents ([http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=409482 GUI editing to text breaks contents], and some wiki link formats).

?Anchor(portal-howto)

Turning pages into portals

To make your article into a portal page, add the tag CategoryPortal to its [#footer footer] and find an appropriate portal to attach it to.

Don't create portals full of dead links.

?Anchor(portal-idb)

Image Data Base

Commonly-used icons and portal logos can be centralized to ["Portal/IDB"]. This is useful for translated portals and for making artwork consistent.

?Anchor(translation)

Translations

?Anchor(link-to-translations) The top of each page shows links to the same page in other languages - see [#article-header Headers], and DefaultTemplate as an example.

?Anchor(translation-page-name)

The principles:

  • Any topic given a wiki page may have many translations, but there is always one "base" page.
  • Since this master copy has to be in some language, we standardize on using the US English version.
  • Translated pages use the naming scheme "[http://www.debian.org/international/l10n/po/ languagecode]" + "/" + "EnglishName" - for example:

    • Base version: ["Hardware"]
    • French translation: ["fr/Hardware"]
  • When you modify a translated page, update or notify the English version too.
  • Try to keep the layout the same in every language, since it simplifies synchronization (especially, editors who aren't fluent in your language will still have some chance of finding and updating the right element).
  • If the page doesn't exist in English, create that too. If you don't feel comfortable writing in English, just create a page with the usual headers and link to your translated page, making sure you tag your page with UpdateEnglish.

  • If the page doesn't exist in your language, start by copy/pasting it from the English version and updating the page header to match the page name, then see below.

?Anchor(translation-synchronize)

Synchronizing translations

When you're updating a page to match one in another language (i.e "synchronizing" the versions),

  • All versions of a page should keep the same layout (formatting, paragraph order, etc.).
  • Keep the revision status of the page clear:
    • (either) update the whole page at once, and then change the matching "revision" number in the header
    • (or) add a comment like ## TRANSLATION UPDATE STOPPED here where you stop.

  • If the translated page is newer than the English one:
    • (either) update the English version yourself if you can (don't worry about minor language errors - someone will correct them)
    • (or) append an "UpdateEnglish" tag at the bottom of the page, and add "+ IMPROVEMENTS" to the English revision comment.

?Anchor(translators)

Wiki translators

People involved in translating Debian Wiki pages should add the tag ["CategoryWikiTranslator"] on their homepage.

?Anchor(helping)

Helping wiki.debian.org

Everyone can help improving wiki.debian.org :

  • Improve the content of any page, where you can.
  • Add your remarks and questions at the bottom of the wiki page you visit.
  • Spell checking pages (many contributions are made by non native English speakers)
  • [#translation Translate] pages.
  • Search [:BackLink:backlinks] to ["?HelpWanted"], ["FixMe"] and ["ToDo"].

  • ["ReFactor"] anything you can

  • Cleanup ["ThreadMode"]

  • Transmit your knowledge (How to install, use or do something with Debian)
  • If you don't work in IT, you can create a page to explain how you use computers in your day-to-day work. Explain your problems and needs.

Debian also needs non-IT skills (legal ; marketing ; organizing events ; press relation and much more ; fund raising).

see also : [http://www.debian.org/intro/help].

?Anchor(promote)

Promote the use of wiki.debian.org

The best and easier way to promote this wiki is to :

  1. Use it.
  2. Put useful content in it (keep the [:../Content#criteria:Content Criteria] in mind).
  • When someone ask a question in a mailing list, forum, irc channel :
    1. Point him/her to official Debian document (www.debian.org/* , man page, README, etc.) best ?BR suggest improvement to author or maintainer if needed.

    2. or update the appropriate wiki page to make sure it answers his/her question, then point him to the page. 2nd best choice

?Anchor(faq)

Frequently Asked Questions

Can I list all the pages on this wiki ?

["TitleIndex"]

I would like a more structured Debian wiki, without orphan articles

Structure is overrated. See [http://c2.com/cgi/wiki?LimitsOfHierarchies]

Is there a way to show just the orphan articles ?

["OrphanedPages"] (this is broken : links in the form [:PageName:Link Label] aren't counted).?BR BTW, there's nothing wrong with orphan page : visitors can/should use search !

?Anchor(pages-changes) ?Anchor(track-changes)

Keeping track of changes
  • The List of recent changes, anywhere on this wiki, click the ?GetText(RecentChanges) link in the menu (limited to 7 days for visitors ; 90 days for logged-in users.).

  • The History of a page Page (the list is limited in number of entries, usually enough for normal pages.)

  • The list of User contributions (AFAIK, moinmoin offers no way to summarize someones contributions. see the two options above).

  • Subscribe to pages : you can subscribe to a page to be notified by email when it's modified (check you ?GetText(UserPreferences), in the menu bar.).

?Anchor(technical)

Technical Information

This Wiki is running [http://moinmo.in/ moinmoin] software, version 1.5 (wiki [:SystemInfo:configuration information]). It currently runs on [http://db.debian.org/machines.cgi?host=ries ries].