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.

?Anchor(account)

Your Account

Your WikiHomePage

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

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

Subscribe to pages

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

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].")

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)

?Anchor(footer)

?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"].

?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

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!

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

?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

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

?Anchor(create)

Creating a page

Before you create a page, ask yourself some questions:

if you decide to proceed:

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:

If you decide to actually rename 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:

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:

Try to preserve page history:

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(translation-page-name)

The principles:

?Anchor(translation-synchronize)

Synchronize contents

Some recommendations :

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

?Anchor(translators)

Wiki translators

People involved in translating Debian Wiki pages can (should) add CategoryWikiTranslator at the end of their homepage.

?Anchor(helping)

Helping wiki.debian.org

Everyone can help improving wiki.debian.org :

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

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