This page provides instructions for people willing to edit the content of wiki.debian.org.
There's a [:DebianWiki/EditorQuickStart:?QuickStart] for new editors.
For generic help on formating under moinmoin wiki, read moinmoin's ["HelpContents"] pages (in the sidebar). ["?SyntaxReference"] is handy. You can experiment in ["WikiSandBox"])
If you disagree with any statement below, comment it out, then start a new discussion thread in the [:DebianWiki/ConventionsDiscussion:discussion] page
?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 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...)
make sure you add CategoryHomepage at the bottom of your homepage.
Subscribe to pages
- You could subscribe to the pages relevant to your subjects of interest.
?Anchor(lost-password)
Lost Password
If you lost your wiki.debian.org password, goto to the page ["?UserPreferences"], then follow the instructions (type your email, then click on ?GetText(Mail me my account data)...)
There's currently a bug in moinmoin : The you should add "=" at the end of the password hash you will receive by email (read [http://lists.debian.org/debian-www/2008/01/msg00252.html explanations]).
?Anchor(writing-style)
Writing Style / WikiEtiquette
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 also: this GoodStyle page.
?Anchor(links)
Links
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 a page is properly named (as it should be), "link title" = "page name".
If a link is within a paragraph, it can be reformatted as lower cased, space separated, and shorten if the context is clear, like [:SampleLong/PageName:page name] .
A link that is not in a paragraph, like a list of See also links, should be left intact ["PageName"] (don't rewrite link wit h [:PageName:Another title].
- Links pointing to a page in another language, append "(in language)", like
[:FR/QuelqueChose:SomethingInFrench] (in french)
See also: moinmoin's ["HelpOnLinking"]
?Anchor(internal-links)
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)
Link to external sites
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].)
- Group external links in the last section of the page.
Call this section External links
Homepage is presented in the External Links (or See also sections of the page if there are no other external links)
Use ["InterWiki"] format to link to packages.debian.org, bugs.debian.org, RFC and Wikipedia.
?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(formating)
Formating
?Anchor(article-header)
Page Header
link to translated version (important to search if exist!): Translation(s): [:German/DebianWiki/EditorGuide:Dutch] - [:French/DebianWiki/EditorGuide:Français]
For sensitive pages, insert a Discussion link: (!) [:/Discussion:Discussion]
Refer to DefaultTemplate to respect the way
?Anchor(footer)
Footer
- Footer is optional
- Insert [#categories Categories] for relational structure
- Insert a section like "See also" for transversal links
Refer to DefaultTemplate to respect the way
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)
[[TableOfContents(2)]]
?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 :
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"].||
?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.
inline:Portal/IDB/official-doc.png |
http://www.debian.org/somewhere - Sample topic |
sample:
||<tablestyle="width:100%;" style="width:32px;border-color:#ff9ec2" >inline:Portal/IDB/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.
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. (do not abuse this ! do not duplicate content everywhere !)
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 ["InstallingDebianOn"] and ["InstallingDebianOn/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(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.
- The GUI editor may break your layout.
?Anchor(images)
Image, Media and attachments
See also: moinmoin's ["HelpOnLinking"].
?Anchor(attachments-credits)
Credits and Copyright
- Add Credits and Copyright information at the bottom of the page where you attach an image, typically :
## attachements : ## openlogo-100.jpg Copyright:1999 "Software in the Public Interest" from http://www.debian.org/logos/openlogo-100.jpg
attachment location
- 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(tags)
Tagging 'Work needed'
- Don't tag at the top of the page. Warning tag is for authors, not for readers
- Insert tag on the [#footer footer] page
- Tag must be less aggressive as possible like:
Using categories
{i} CategoryRedundant: [:ARedundantPage:A redundant page], [:AnotherRedundantPage:Another Redundant Page]
CategoryRedundant: [:ARedundantPage:A redundant page], [:AnotherRedundantPage:Another Redundant Page]
Using tags
?Include(WikiTag)
Note: do not use the [http://moinmo.in/HelpOnProcessingInstructions #deprecated] processing instruction, as it prevents further edition of the page, like fixing broken links and so on. If you need a page that needs to be improved/removed, use an appropriate ["WikiTag"] instead.
?Anchor(pages)
Pages
?Anchor(pages-name)
URL / page naming convention
Use only CamelCase formatting (as opposed to Underscore_Separated).
- First letter of first word should be upper case.
- 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, see [#translation Translation section].
- Choose a significant name is important. The page name shouldn't 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 :
- Choose a name for a page. see [#pages-name URL / page naming convention].
Search a portal page of the new one with CategoryPortal page (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 recommended)
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 when other people "improve" it.
- 3. Consider subscribing to that page.
See also: moinmoin's ["HelpOnPageCreation"].
?Anchor(rename)
Rename a page
Cool URIs don't change ([http://www.w3.org/Provider/Style/URI w3]). Still, sometime it's a good idea to rename a page when it's 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 for a page. see [#pages-name URL / page naming convention].
- 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" ! ).
- 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 [#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 Merging and Splitting pages] instead)
- translation consideration : delete translated pages too !
If you think a page should be removed, you can either :
- Delete the page your self (write the reason in comment field).
or Tag the page with "CategoryProposedDeletion" so other editors can react (i.e. put the tag and explanation at the bottom of the page).
?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 "Comment" 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"]
See also: moinmoin's ["HelpOnProcessingInstructions"].
?Anchor(categories)
Categories
moinmoin wiki's help : [:HelpOnCategories:using categories].
The list of categories used on this wiki ["CategoryCategory"].
?Anchor(portal)
Portal
Portals are hub pages containing 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].
Portal pages should be based on PortalTemplate.
Do not use Edit(GUI) since it will break some wiki contents ([http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=409482 GUI editing to text breaks contents], and some wiki link formats).
?Anchor(portal-howto)
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 in the [#footer footer] of your page
Your page must only contain active [#links links] to another articles (like as hub page or a node). Don't create dead links.
?Anchor(portal-category)
Portal and Categories
If a portal covers a very large subject (it has more than 40 related pages), then you can create a Category that match your portal name (for example Software have CategorySoftware).
- These Categories are just a redirection to corresponding Portals
Example: CategorySoftware contain #reditect Software
In Articles, you can insert reference to portals using CategoryFooBar in the footer.
?Anchor(portal-idb)
Image Data Base
You can centralize re-used icons and logos of portals to ["Portal/IDB"]. It's useful for translated portal and to have homogeneous artwork.
?Anchor(translation)
Translations
?Anchor(translation-page-name)
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 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
- Example:
(optional) 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
- Example:
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 :
- copy paste English version in it.
- update the page header to match Translated page one.
- see synchronise contents.
?Anchor(translation-synchronize)
Synchronise contents
Some recommendations :
- 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 :
- Update The English version yourself if you can (don't be afraid to make mistake someone would correct them).
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
People involved in translating Debian Wiki pages can (should) add CategoryWikiTranslator at the end of their homepage.
The list of translators : ["CategoryWikiTranslator"]
?Anchor(helping)
Helping wiki.debian.org
Everyone can help improving wiki.debian.org :
- Improve the content of any page, where you can.
- Add your remarks and questions at the bottom of the wiki page you visit.
- Spell checking pages (many contributions are made by non native English speakers)
- [#translation Translate] pages.
Search [:BackLink:backlinks] to ["?HelpWanted"], ["FixMe"] and ["ToDo"].
["ReFactor"] anything you can
Cleanup ["ThreadMode"]
Delete Spam : ["?DealingWithSpam"]
- Transmit your knowledge (How to install, use or do something in Debian)
- If you don't work in IT, you can create a page to explain how you use computers in your day-to-day work. Explain your problems and needs.
Debian also need non-IT skills (legal ; marketing ; organising events ; press relation and much more ; fund raising).
see also : [http://www.debian.org/intro/help].
?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 the [:../Content#criteria:Content Criteria] in mind).
- When someone ask a question in a mailing list, forum, irc channel :
Point him/her to official Debian document (www.debian.org/* , man page, README, etc.) best ?BR suggest improvement to author or maintainer if needed.
or update the appropriate wiki page to make sure it answers his/her question, then point him to the page. 2nd best choice
?Anchor(faq)
Frequently Asked Questions
- 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 !
?Anchor(pages-changes) ?Anchor(track-changes)
- Keeping track of changes
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
This Wiki is running [http://moinmo.in/ moinmoin] software, version 1.5 (wiki [:SystemInfo:configuration information]). It currently runs on [http://db.debian.org/machines.cgi?host=ries ries].
?Anchor(wpas)
Wiki Policy Approbation System
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:
- 1). Discussion any where on this Wiki.
2). Discussion speak about a policy, move it to ["DebianWiki/ConventionsDiscussion"]
- 3). Try to create a stable discussion
4). Discussion is stable ? try to suggest a resolution ( Policy suggestion) (if not, return to point (3.)
5). 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.