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"]
Table of Contents?TableOfContents(2) |
?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 location (city and country) useful for timezone consideration and more 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 a ToDo/done list Some cool hints about Debian + put a copy on ?HintsnTips. make sure you add CategoryHomepage at the bottom of your homepage.
?Anchor(writing-style)
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 VisualBalance, but also an attempt to AvoidBias. If you find that your comments are controversial, sign them, so that others will feel more free to disagree publicly. Don't make EveryThing into a UselessWikiName. Knowing when to make a new page is one of the hardest parts of WikiStyle. RefactorMercilessly There is no page in the WikiUniverse that is finished. All content can be refined. See RefactoringWikiPages for many useful thoughts. If the wiki topic is fairly long then it would be good style to give a quick overview of what has been discussed in the topic as a sort of concluding paragraph. If a concluding paragraph cannot be easily written then perhaps the scoping of the topic was not right and should separated into subtopics or should be merged with other topics into one larger topic. This is common when ThreadMode meanders off topic. See alos: this GoodStyle page. ?Anchor(pages)
?Anchor(pages-name)
Use only CamelCase formatting Example: Moinmoin documentation [:HelpOnEditing/SubPages:?SubPages] Translated pages begin with the name of Language ?Anchor(create)
Before you create a page, ask your self some questions : Would it match wiki.debian.org [:DebianWiki/Content:Content Criteria] ? if you decide to proceed : Search a portal page of the new one with CategoryPortal page (you may find more than one, choose the best) Pick the appropriate template If your page relates to a subject already covered by some official Debian documentation, link to it at the top See also: ["HelpOnPageCreation"]. ?Anchor(rename)
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. If you decide to actually rename the page : note: If you feel like creating a "redirect" page, it might means that the page shouldn't be renamed ! ?Anchor(delete)
Read the [#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 [#merge-and-split merge] instead) ?Anchor(merge-and-split)
It's a good idea, Your are encouraged to : Splitting a very-long page that cover different subject ?Anchor(redirect-page)
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 : If the page was moved you can use : See also: ["HelpOnProcessingInstructions"]. ?Anchor(article-header)
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!): Translation(s): [:German/DebianWiki/EditorGuide:Dutch] - [:French/DebianWiki/EditorGuide:Français] Insert Discussion link: (!) [:/Discussion:Discussion] Refer to DefaultTemplate to respect the way ?Anchor(footer)
Refer to DefaultTemplate to respect the way ?Anchor(discussion)
[:/Discussion:Discussion] (!) [:/Discussion:Discussion] See ["DefaultTemplate"] if necessary
sample: (notice the space at the beginning of the lines)
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) ?Anchor(disambiguation)
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: ?Anchor(tags)
When you merge a page, sometimes, it's right to keep dead page and convert it as a redirection #redirect-page MergingPage ?Anchor(official)
Sample link presentation to some official page, related to current subject. inline:FranklinPiat/official-doc.png http://www.debian.org/somewhere - Sample topic sample: ToDo: The image should be moved to moinmoin static-content folder. It would be nice to use CSS stylesheet and Class too. ?Anchor(portal)
Portals are hub pages containning links to articles. They propose a structural point of view. It's a complement with the relational structure offer by CategoryCategory and the [:FindPage:integrated search engine]. The main portal is the FrontPage. the next release of this page is ["FrontPage/Testing"] ?Anchor(portal-name)
?Anchor(portal-header)
Portals banners include: Path like: [:FrontPage:Frontpage] > [:Portal_AThing:A thing] > Current Portal Translation links: Translation(s): [:German/DebianWiki/EditorGuide:Dutch] - [:French/DebianWiki/EditorGuide:Français] Insert Discussion link: (!) [:/Discussion:Discussion] Refer to PortalTemplate to respect the way ?Anchor(portal-howto)
If you want your article page becomes a portal page, follow instructions below: Attach your your portal to another portal Include the CategoryPortal in the [#footer footer] of your page Your page must only contain [#links links] to another articles Update the [:?DebianWiki/PortalMap:map of portals] ?Anchor(portal-idb)
You can centralize icone and logo of portals to ["Portal/IDB"]. It's useful for translated portal and to have homogeneous artwork. ?Anchor(links)
Except in a portal page, 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 the [#footer "See also" section at the bottom of your page] (but again, not too many). Assuming that if a page is properly named (as it should be), the "link title" = "page name" 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)'' [:FR/QuelqueChose:SomethingInFrench] See also: ["HelpOnLinking"] ?Anchor(internal-links)
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)
The preferred way to link to external resources is : [http://www.debian.org/doc/] - Debian Official documentation repository. (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)
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)
See also: ["HelpOnLinking"]. ?Anchor(categories)
moinmoin wiki's help : [:HelpOnCategories :using categories]. The list of categories used on this wiki ["CategoryCategory"]. ?Anchor(promote)
The best and easier way to promote this wiki is to : ?Anchor(pages-changes)
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 ( 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 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)
ToDo: write this paragraph ?Anchor(complex-formating)
AVOID using It's difficult to read the diff of complex formatings. ?Anchor(translation)
This is a proposal. The debian-i18n team should be asked for advice. Until then, please keep using the current scheme ( French translation of Sample should be named ?SampleFrench ) The principles: 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 Translated page is named like "Language" + "/"+ "?NameOfReferentPage" Referent page: ?SomeThing (optionnal) To help user that doesn't speak english, you can create a Content of the linker: #redirect 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 ?Anchor(translation-synchronize)
Some recommendations : If you can't update the synchronisation of the whole page at once, add a comment like ## TRANSLATION UPDATE STOPPED here where you stop. Or tag the page with "?UpdateEnglish" (at the bottom), and add "+ IMPROVEMENTS" to the ?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)]
People involved in translating Debian Wiki pages can (should) add CategoryWikiTranslator at the end of their homepage. The list of translators : ["CategoryWikiTranslator"] ?Anchor(helping)
Everyone can help improving wiki.debian.org : Debian also need non-IT skills (legal ; marketing ; organising events ; press relation and much more ; fund raising) ?Anchor(faq)
see [:DebianWiki#helping: Helping DebianWiki]. Cleanup ["ThreadMode"] ["ReFactor"] anything you can Delete Spam : ["?DealingWithSpam"] Search [:BackLink:backlinks] to ["?HelpWanted"], ["FixMe"] and ["ToDo"]. ["TitleIndex"] Structure is overrated. See [http://c2.com/cgi/wiki?LimitsOfHierarchies] ["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(wpas)
All [:DebianWiki/ConventionsDiscussion: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, move it to ["DebianWiki/EditorGuide"]. We can resume Policy creation process by: Discussion speak about a policy, move it to ["DebianWiki/ConventionsDiscussion"] Discussion is stable ? try to suggest a resolution Resolution is stable 10 days ago, move it to ["DebianWiki/EditorGuide"] and move old discussion to "Old discussions" section (if not, return to point 3.) For important subject and, if discussion can't stabilized, you can propose a [:?DebianWiki/WikiVote:wikivote] as resolution. Subscribe to pages
Writing Style / WikiEtiquette
Article
URL / page naming convention
(see [#translation Translation section] above) Create a Page
(DefaultTemplate is recommanded) Rename a page
Delete a page
Merging and Splitting pages
(but consider adding a [[TableOfContent]] instead.). Remember : too many empty pages are just boring for visitors. Redirect pages
#redirect DestinationPage
goto to ["DestinationPage"]
#refresh 5 DestinationPage
This page moved. update your bookmark : ["DestinationPage"]
Page Header
Footer
URL for Discussion
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.
Table of Contents
||<style="font-size:smaller">[[TableOfContents(2)]]||
Disambiguation page header
||<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"].||
Tags
Warnings
(Optional for short, obligatory for important article) {i} [:CategoryRedundant:Redundant pages]: [:ARedundantPage:A redundant page], [:AnotherRedundantPage:Another Redundant Page]
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.
||<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||
Portal
Naming
Header
Define article as portal
(hierarchical structure) Image Data Base
Links
(in french) Internal Links
Link to external sites
Link from external sites
Image and Media
## attachements :
## openlogo-100.jpg Copyright:1999 "Software in the Public Interest" http://www.debian.org/logos/openlogo-100.jpg
Categories
Promote the use of wiki.debian.org
Page Fragments
included in another should be named */!PageFragment/* Keeping track of changes
Technical Information
Advanced Formating / Complex Formating
Translations
Referent Page. When you modify a translated page, you must update or notify the referent page Synchronise contents
English revision comment. Wiki translators
Helping wiki.debian.org
Frequently Asked Questions
Wiki Policy Approbation System
( Policy suggestion) (if not, return to point (3.)