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

• Use only CamelCase formatting

• First letter of first word should be upper
• 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: Translation 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

• [:#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

• 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

#redirect DestinationPage
goto to ["DestinationPage"]

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

• 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

?Anchor(footer)

Footer

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

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

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

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

• Include the CategoryPortal at the bottom of your page

• Your page must only contain [:#links:links] to another articles (like as hub page or a node).

• Update the [:?DebianWiki/PortalMap:map of portals]

?Anchor(links)

Links

• If a link is within a paragraph, it can be reformated [:PageName:page name] (i.e lower cased, space separated, and shorten if the context is clear).

• A link that is not in a pagraph (list of [:#footer:See also]...), then it should be left intact ["PageName"].

• Links pointing to another language finish with ''(in language)''

  • Example:

    • [:FR/QuelqueChose:SomethingInFrench] (in french)

Engine reference: [:HelpOnLinking:using links]

?Anchor(internal-links)

Internal Links

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

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

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

Translations

• 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 "Language" + "/"+ "?NameOfReferentPage"

  • Example:

    • Referent page: ?SomeThing

    • French page: French/Something

• (optionnal) To help user that doesn't speak english, you can create a linker page named "Initial of language" + "/" + "?PageInNativeLanguage". This page redirect to the translated page with the content #redirect "Language" + "/"+ "NameOfReferentPage"

  • Example:
    • Linker page: FR/QuelqueChose

    • Content of the linker: #redirect French/Something

    • Translated page: French/Something

• One should attempt to keep the same layout in every languages (1. it's easier to synchronise 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.
  2. update the page header to match Translated page one.
  3. see synchronise contents.

?Anchor(translation-synchronize)

Synchronise contents

• 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 synchronising pages), try updating the whole page at once, then change the matching "revision" number in the header.

  • If you can't update the synchronisation 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.

[[Anchor(translators)]

Wiki translators

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