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

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

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

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

?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(pages)

Pages

?Anchor(pages-name)

URL / page naming convention

• Use only Moinmoin:CamelCase formatting

• First letter of first word should be upper. (["debconf"] + ["DebConf"])

• Special characters shoud be avoided in page names.
• Using slash should be use to group same pages. If your page clearly belongs to a collection, you might consider creating it as a subpage

  • Example: Moinmoin documentation [:HelpOnEditing/SubPages:?SubPages]

• Translated pages begin with the name of Language (see [:#translation: Translastion section] above)

• Choose a significant name is important. The page name shouldn't ambiguous. Some ambiguous.
  • Counter-example: "About"... about what ?? about Debian wiki, organisation, Operating system, etc..
  • Counter-example: "Release"... would it be : previous release, current release, life cycle, future release status, release process, release team, etc...
• Name should clearly state what the page is about and should contain the word visitors will search.

?Anchor(create)

Create a Page

Before you create a page, ask your self some questions :

• Is the page really needed ? Doesn't it already exists (with another name) ? What about adding the content to an existing page ?

• Would it match wiki.debian.org [:DebianWiki/Content:Content Criteria] ?

if you decide to proceed :

• [:#pages-name:Choose a name for a page].

• Search a [:CategoryPortal:portal page] of the new one (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 recommanded)

• If your page relates to a subject already covered by some official Debian documentation, link to it at the top (see [:#official:Debian official stuff])

• Once the page is complete, make links to it from relevant pages (1 link is often enough).

• more hints :

  • 1. Re-read it two days later (still looks good ?)
  • 2. This page isn't "yours" don't be offended other people "improve" it.
  • 3. Consider subscribing to that page.

+ some [:DebianWiki/Translation#new-page:Translation] considerations. ?BR + more in Moinmoin documentation : ["HelpOnPageCreation"].

?Anchor(rename)

Rename a page

Rule #1.1 would be : Don't rename pages. But sometimes, it's still a good idea when the page name don't accurately describe the page content.

Before you rename a page:

• Use google (or equivalent) to search if this page is linked from outside this wiki. Search link:wiki.debian.org/FooBar. If it is referenced, consider twice before renaming the page. if you rename the page, consider putting a refresh (see [:#redirect-page:redirect] page) and contact the owner of 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:Choose a name for a page].
• Make sure you update all the pages that used to point to the old name (type the previous page name in the search bar, then click "Text" ! ).

+ some translation consideration : also take care of translated version of the page.

note: If you feel like creating a "redirect" page, it might means that the page shouldn't be renamed !

?Anchor(delete)

Delete a page

read the [:?DebianWiki/WikiPage#rename:Rename a page] hints, since they apply here too.

• don't be rude : do not copy-paste content of existing page in a new one, and delete an old page : this would cause page history to be lost. (see [#rename rename] and [#merge-and-split merge] instead)

+ translation consideration : delete translated pages too !

?Anchor(merge-and-split)

Merging and Splitting pages

It's a good idea, Your are encouraged to :

• Merge pages covering the same subject (duplicate).
• Merge similar page, if both are "too short".

• Splitting a very-long page that cover different subject (but consider adding a [[TableOfContent]] instead.). Remember : too many empty pages are just boring for visitors.

• when you merge or split pages, include source and destination pages in the changelog (i.e in the "Optional comment about this change" field). Note: Merge pages in an existing one, not in a new one, in order to preserve page history.

+ translation consideration : 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 occasion, you might want to create a "redirect" page (which automatically redirect the browser to the proper page). hint: Don't over-use this tool.

sample :

#redirect DestinationPage
goto to ["DestinationPage"]

If the page was moved you can use :

#refresh 5 DestinationPage
This page moved. update your bookmark : ["DestinationPage"]

+ moinmoin documentation's on redirect and refresh in ["HelpOnProcessingInstructions"].

?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(portal)

Portal

?Anchor(portal-name)

Naming

• Portal naming is identical like article naming convention

?Anchor(portal-content)

Define article as portal

If you want your article page becomes a portal page, follow instructions below:

• Attach your your portal to another portal (hierarchical structure)

• Include the CategoryPortal at the bottom of your page

• Your page must only contain links to another articles (it's like an hub page or a node).

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