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

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

Work in progress. If you disagree with any statement below, comment it out, then start a new discussion thread in the [:?DebianWikiConventionsDiscussion#editor-guide:Discussion] page

• ?TableOfContents(2)

Read Moinmoin's [:HelpContents:Help] pages too (moinmoin is the wiki engine).

?Anchor(account)

Your Account

• Your wiki username would be in the format "FirstnameLastname" ("IrcNickname" or your debian developer login are used sometimes).

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

Your WikiHomePage

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

• Your full name.
• Your main homepage outside this wiki.
• Your email

• Your location (city and country) useful for timezone consideration and more

• If you use IRC, tell about your usual server, channel and nickname

• If you are a Debian Developer (DD), provide your login name + link to http://qa.debian.org/developer.php?login=foobar@debian.org

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

• List your subjects of interest (not limited to Debian).

• a ToDo/done list

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

• Some cool hints about Debian + put a copy on ?HintsnTips.

make sure you add CategoryHomepage at the bottom of your homepage.

Subscribe to pages

• You could subscribe to ?DebianWiki/WikiMailAnnouncements : major modification to this wiki will be notified here ( ToDo: anyone has a better / more explicit page name so suggest ? )

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

?Anchor(writing-style)

Writing Style / WikiEtiquette

• Read this GoodStyle page.

?Anchor(formating)

Formating

This wiki has some formating conventions. Here are the most used ones.

For generic help on formating under moinmoin wiki, read moinmoin's ["?SyntaxReference"], ["HelpOnEditing"]. You can experiment in ["WikiSandBox"].

?Anchor(banner)

Page Header

• Portals banners includes:

  • Path like: [:FrontPage:Frontpage] > [:Portal_AThing:A thing] > Current Portal

  • Indicate translation links
  • Insert Discussion link

  • Refer to PortalTemplate to respect the way

• Article banner includes:
  • Try to attach your page to a portal page

  • Path like: [:FrontPage:Frontpage] > [:Portal_AThing:A thing] > Current Page or, if page is not attached to a portal,  [:IndexPage:Index page] > Current page . in this case, Index must be attached to a portal

  • Indicate translation links (very important to search if exist!)

  • Insert Discussion link

  • Refer to DefaultTemplate to respect the way

Footer

• Footer is optinal
• Insert Categories
• Insert a section like "See also" for transversal links.
• Insert tags

• Refer to DefaultTemplate to respect the way

?Anchor(discussion)

URL for Discussion

• Each banner could include a discussion link like:

  [:/Discussion:Discussion]

 (!) [:/Discussion:Discussion]

• This Discussion link is optionnal. Use it only when needed.

• See ["DefaultTemplate"] if necessary

Format an FAQ sections

A typical FAQ section could be formated like :

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

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

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

 ||<style="font-size:smaller">[[TableOfContents(2)]]||

ToDo : we should use a CSS style instead + custom stylesheet..

?Anchor(disambiguation)

Disambiguation page header

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

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

Warnings

• Don't tag at the bottom of the page. Warning tag is for authors, not for readers
• Insert tag on the footer page
• Tag must be less aggressive looking like:

  • {i} [:CategoryRedundant:Redundant pages]: [:ARedundantPage:A redundant page], [:AnotherRedundantPage:Another Redundant Page] 

• Page without enough content can be directly merging or remove

• When you merge a page, sometimes, it's right to keep dead page and convert it as a redirection #redirect MergingPage (Optional for short, obligatory for important article)

?Anchor(official)

Debian Official stuff

Often, the content of a Debian wiki page is also covered by some "official" Debian Documentation (or 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 current subject.

• sample:

  ||<tablestyle="width:100%;" style="width:32px;border-color:#ff9ec2" >inline:FranklinPiat/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 static-content folder. It would be nice to use CSS stylesheet and Class too.

?Anchor(links)

Links

Rule #1 would be : Don't overuse linking. The reader wouldn't know which links are useful if there are too many. You can move some of the links in a "See Also" section at the bottom of your page (but again, not too many).

• moinmoin wiki's help : [:HelpOnLinking:using links].

?Anchor(internal-links)

Internal Links

Internal Links (within this wiki)

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

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

3. [:EditorGuide:editor guide] can be used within a sentence to make it more readable.

In all case, make sure that the link label is meaningful to visitors, so he/she reaches what he/she expects (preferably, 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].

?Anchor(links-to-www)

Link to external sites

The preferred way to link to external resources is :

• [http://www.debian.org/doc/] - Debian Official documentation repository.

An alternate option is

• Debian Official documentation repository ?BR [http://www.debian.org/doc/]-~.

(avoid the notation  [http://www.foo.com link label]  because the target is obscure for visitors. However, it's ok to use it when the context make it clear, like :"John Doe provides a script named [http://www.johndoe.org/test.sh test.sh].")

Use ["InterWiki"] format to link to packages.debian.org, bugs.debian.org, RFC and ?WikiPedia.

?Anchor(links-from-www)

Link from external sites

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

• 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.?BR?BR or

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

?Anchor(pages-changes)

Page Fragments

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

• 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 [[Include()]] macro in ["HelpOnMacros"]

a sample is available at ["Installing Debian On/FrontPage"] and ["Installing_Debian_On/PageFragments/Philosophy"]. Also note how the page is included inside a table (but don't use this hack to bypass moinmoin formating limitation : see [#complex-formating Complex Formating]).

?Anchor(track-changes)

Keeping track of changes

ToDo: write this paragraph

• 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

ToDo: write this paragraph

• moinmoin Software.

?Anchor(complex-formating)

Advanced Formating / Complex Formating

AVOID using advanced formating using table, include, etc.

• It's difficult to understand and maintain for you and other wiki editors.

• It's difficult to read the diff of complex formatings.

?Anchor(pages)

Pages

Wiki page Creation, Deletion/removal, naming, renaming, merging, splitting are explained in [:?../WikiPage:?../WikiPage].

?Anchor(translation)

Translations

A Wiki page [:?../TranslationGuide:Translation guide] (naming page, synchronize with other languages and more).

?Anchor(faq)

Frequently Asked Questions

Where can I help ?

• see [:DebianWiki#helping: Helping DebianWiki].

• Cleanup ["ThreadMode"]

• ["ReFactor"] anything you can

• Delete Spam : ["?DealingWithSpam"]

• Search [:BackLink:backlinks] to ["?HelpWanted"], ["FixMe"] and ["ToDo"].

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 !

Wiki Policy Approbation

• All discussions finish by a resolution. Resolution is a synthesis of discussion, point by point. If no one relaunch discussion after 10 days, resolution is validate.

  Once resolution validate, it move to ["DebianWiki/EditorGuide"]. We can resume Policy creation process by:

• Discussion any where on this Wiki

• Discussion speak about a policy, move it to ["?DebianWikiConventionsDiscussion"]

• Try to create a stable discussion

• Discussion is stable ? try to suggest a resolution ( Policy suggestion) (if not, return to point (3.)

• Resolution is stable since 10 days, move it to ["DebianWiki/EditorGuide"] and move old discussion to "Old discussions" below (if not, return to point 3.)