DebianWiki/EditorGuide - Debian Wiki

Translation(s): English - Español - Français - Indonesia - Português (Brasil) - Português (Portugal) - Русский - Українська - 简体中文српски-~

(!) Discussion

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

There's a QuickStart for new editors.

(!) See also: HelpOnSmileys :-) HelpOnMacros and HelpOnLinking and short HelpOnEditing

For generic help on formatting under moinmoin wiki, read moinmoin's HelpContents pages (in the sidebar). Syntax reference 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 discussion page.

Your Account

Your WikiHomePage

You can use the HomepageTemplate when you create your homepage. Here are ideas for content, grabbed from various existing homepages.

Make sure you keep the CategoryHomepage tag at the bottom of your homepage (present by default in the HomepageTemplate).

Contacting you

If you are editing the wiki a lot, you might want to include your contact information on your WikiHomePage and also join the debian-www mailing list and #debian-www IRC channel (web version).

Subscribe to pages

Lost Password

If you lose your wiki.debian.org password, go to the page recoverpass, then follow the instructions there (type your email address, then click on "Mail me my account data").

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 visual balance, but also an attempt to avoid bias. If you find that your comments are controversial, sign them, so that others will feel more free to disagree publicly.

See also this GoodStyle page.

Links

Don't overuse linking. If there are too many, the reader won't know which links are useful. You can move some of the links to a "See also" section at the bottom of your page (but again, not too many).

Where links point to a page in another language, append "(in $language)", thus: ?Something (in French)

See also moinmoin's HelpOnLinking

Internal Links (within this wiki)

  1. [[FooPage]] is usually the preferred syntax.

  2. [[SomeParentPagewith/FooPage|FooPage]] is frequently used to shorten subpages.

  3. [[EditorGuide|editor guide]] can be used to help fit the link name into a sentence as normal lower-case words.

  4. Don't "rename" the link by using [[PageName|Another title]] (if you have to do this, it implies the page is misnamed).

In all cases, make sure that the link label is meaningful to visitors, and that the link doesn't lead somewhere unexpected (preferably, the 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]] (where Bar Chapter is the actual paragraph title).

The preferred way to link to external resources is:

(Avoid the notation  [[https://www.example.com|link label]] , which hides the target URL, unless the context makes it clear, as in "John Doe provides a script named test.sh.")

Use InterWiki format to link to Debian packages, bugs, RFCs and Wikipedia articles.

If an (important) page is linked from outside Debian, it's a good idea to tag it with CategoryPermalink, so that nobody removes it inadvertently.

Formatting

Header sections

Material that naturally belongs in an (optional) "header" area at the top of the page includes:

To ease the updating and synchronization of the translation headers of all the language versions of a page, the English version's is the only one that should be modified, and included in all translated versions via the macro Include. To accomplish this, the translation header in the English version, must be surrounded by special comment tags, which will tell the macro Include what to include in the translated pages.

  1. In the original English page

    1. Make sure the English language is a self-referencing link to the English page itself (not a simple text), like this: [[<PageName>|English]].

    2. Insert this before the line with the list of translations (remember to substitute <PAGENAME> for the actual page name):

      ##For Translators - to have a constantly up to date translation header in you page, you can just add a line like the following (with the comment's character at the start of the line removed)
##<<Include(<PAGENAME>, ,from="^##TAG:TRANSLATION-HEADER-START",to="^##TAG:TRANSLATION-HEADER-END")>>
##TAG:TRANSLATION-HEADER-START

    3. Insert this after the line with the list of translations:

      ##TAG:TRANSLATION-HEADER-END
  2. In your translated page

    1. Insert this instead of the translation line (remember to substitute <PAGENAME> for the actual page name):

      <<Include(<PAGE_NAME>, ,from="^##TAG:TRANSLATION-HEADER-START",to="^##TAG:TRANSLATION-HEADER-END")>>

See the DefaultTemplate and its translations for examples on this and how it works.

Disambiguation banner

Sometimes, a page's name can be ambiguous. If this can't be avoided, you can insert something like this at the top of the page:

Disambiguation : This page is about Debian Conferences.
For Debian configuration management system, see debconf.

Debian "official material" banner

Often, the content of a Debian wiki page is also covered by some piece of "official" Debian Documentation (or in some 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 the current subject.

Table of Contents sections

If a page gets long, you might want to add a Table of Contents. See the example at the top of this page!

FAQ sections

A typical FAQ section could be formatted like this:

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.

Material that naturally belongs in an (optional) "footer" area at the end of the page includes:

Page Fragments

Not only code can be be reused - page content can 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 to duplicate content everywhere!)

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 formatting limitations: see Complex Formatting).

Advanced Formatting/Complex Formatting

Avoid using "advanced" formatting (using tables, include, etc.)

Images, media and attachments

See also: moinmoin's HelpOnLinking.

Add credits and copyright information at the bottom of the page where you attach an image, typically: 

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

Attachment location

It's often a good idea to attach the image to the parent page (in case the image is reused in other subpages).

For translated pages, attach the image to the English version (internationalized/localized images should be attached to the internationalized/localized pages).

Screenshots

If you want to include a screenshot, you might want to store it on https://screenshots.debian.net/, then use :

Example:

Image position

https://www.debian.org/logos/openlogo-nd-75.jpg

It is possible to shift the images to right of the page, thanks to CSS' float:right: 

||<tablestyle="float:right; width:100px; background:transparent; margin: 0 0 1em 1em;" style="padding:0.5em; border-style:none;"> {{https://www.debian.org/logos/openlogo-nd-75.jpg}} ||

"Work needed" tags

Translation(s): English - español - Português (Brasil) - Українська

A tag is a WikiName that has special meaning to the community. It is used to group pages, by searching for the tag and seeing all the pages that have it. Under MoinMoin wiki, one should use Categories.

WikiTags related to ongoing work on the wiki can be found at DebianWiki/Administration#Current_tasks.

Note: do not use the #deprecated processing instruction, as it prevents further editing of the page (e.g. to fix broken links). If you need to mark a page as needing to be improved/removed, use an appropriate WikiTag instead.

These tags are meant for wiki editors, not for visitors, so don't make them too intrusive; instead of putting a warning tag at the top of the page, insert it in the page's footer.

Pages

URL/page naming conventions

Creating a page

Before you create a page, ask yourself some questions:

link If you decide to proceed:

See also: moinmoin's HelpOnPageCreation.

Renaming a page

Cool URIs don't change (w3). Still, sometime it's a good idea to rename a page when its name don't accurately describe the page content.

Before you rename a page:

If you decide to actually rename the page:

Note: If the page-rename seems to require a "redirect" page, that might mean that the page shouldn't be renamed!

Deleting a page

Read the Renaming a page hints, since they apply here too.

If you think a page should be removed, you can either:

Don't be rude: do not copy-paste the content of an existing page into a new one, and delete the old page - this loses page history. Instead see Merging and splitting pages.

Again, if there are translated versions, deal with them too!

Merging and splitting pages

Reorganizing pages is a good idea. You are encouraged to:

Try to preserve page history:

For translations: if you can't merge/split translated pages, add directions (comments) in the translated version so translators can keep up!

Redirect pages

On some occasions, you might want to create a "redirect" page (which automatically redirects the browser to the proper page).

Don't over-use this tool.

sample : 

#redirect DestinationPage
go to [[DestinationPage]]

Note that #refresh isn't enabled on this wiki.

See also: moinmoin's HelpOnProcessingInstructions.

Categories

moinmoin wiki's help: using categories.

The list of categories used on this wiki: CategoryCategory.

Portals

Portals are hub pages containing links to articles. They complement the relational structure offered by CategoryCategory, and the integrated search engine.

Portal pages should be based on PortalTemplate.

Turning pages into portals

To make your article into a portal page, add the tag CategoryPortal to its footer and find an appropriate portal to attach it to.

Don't create portals full of dead links.

Image Data Base

Commonly-used icons and portal logos can be centralized to Portal/IDB. This is useful for translated portals and for making artwork consistent.

Translations

The top of each page shows links to the same page in other languages - see Headers, and DefaultTemplate as an example.

The principles:

Synchronizing translations

When you're updating a page to match one in another language (i.e. "synchronizing" the versions),

Wiki translators

People involved in translating Debian Wiki pages should add the tag CategoryWikiTranslator on their homepage and consider helping translate other parts of Debian.

Helping with wiki.debian.org

Anybody can help to improve wiki.debian.org:

Debian also needs non-IT skills (legal; marketing; organizing events; fund-raising; public relations; and much more). See also https://www.debian.org/intro/help.

Promoting wiki.debian.org

The best and easiest ways to promote this wiki are to use it yourself and to make it useful to others by contributing useful material (bear in mind the content guidelines).

When you are asked a question in a mailing list, forum, or irc channel,

Frequently Asked Questions

Q) Can I get a list of all the pages on this wiki?

A) Yes, see TitleIndex

Q) Wouldn't the wiki be more useful if it was better organized?
A) Possibly, but a structured wiki is largely a contradiction in terms. It's more important to give it good content.

Q) Is there a way to show just the orphan articles?

A) No (OrphanedPages is broken; links in the form [[PageName|Link Label]] aren't counted). But being an orphan is only a problem if there are pages that should link to it and don't (so fix those), or if the page fails to show up in searches (so make sure it includes the appropriate keywords).

Q) How do I keep track of changes?
A) By using two features accessible via the sidebar menu:

  • the link to the RecentChanges page (limited to a week for visitors, 90 days for logged-in users);

  • the Subscribe option, which requests e-mail notification when the page is modified.

Technical Information

This Wiki is running moinmoin software, version 1.9 (wiki configuration information). It currently runs on a machine sponsored by Dembach Goo Informatik GmbH & Co KG (both hardware, housing and bandwidth).