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
Some 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"].
Page Header
See ["DefaultTemplate"].
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..
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 :
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"].||
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.
inline:FranklinPiat/official-doc.png |
http://www.debian.org/somewhere - Sample topic |
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 Link
Internal Links (within this wiki)
["FooPage"] is usually the preferred syntax.
[:SomeParentPagewith/FooPage:FooPage"] is frequently used to shorten sub pages.
[: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
External Links (to and from external sites, ["InterWiki"], etc....)
The preferred way to link to external ressources 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.)
?Anchor(links-from-www)
Link from external sites
If an (important) page is linked from outside Debian, it's a good idea to tag it with CategoryPermalink. So nobody removes it inadvertently.
?Anchor(images)
Image and Media
moinmoin wiki's help : [:HelpOnLinking:using images].
- Credits and Copyright consideration
- It's a good idea to add Credits and Copyright information at the bottom of the page where you attach image.
- Where should i attach an image ?
- Sometime, it's a good idea to attach the image to the parent page (in case the image is reused in other sub pages).
- For Translated pages, attach the image to the English version (internationalized/localized images should be attached to the internationalized/localized pages).
?Anchor(using categories)
Categories
moinmoin wiki's help : [:HelpOnCategories :using categories].
The list of categories used on this wiki ["CategoryCategory"].
?Anchor(promote)
Promote the use of wiki.debian.org
The best and easier way to promote this wiki is to :
- Use it.
- Put useful content in it (keep [:/Content#criteria:Content Criteria] in mind).
- When someone ask a question in a mailing list, forum, irc channel :
?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 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)
ToDo: write this paragraph ?Anchor(technical)
ToDo: write this paragraph ?Anchor(complex-formating)
AVOID using It's difficult to read the diff of complex formatings. ?Anchor(pages)
Wiki page Creation, Deletion/removal, naming, renaming, merging, splitting are explained in a separate page : ["?../WikiPage"] ?Anchor(translation)
A Wiki page Translation guide is explained in a separate page :
included in another should be named */!PageFragment/* Keeping track of changes.
Technical Information
Advanced Formating / Complex Formating
Pages
Translations