["FrontPage"] > ["DebianWiki"] > Editor Guide

Translation(s): none

(!) [:DebianWiki/ConventionsDiscussion:Discussion]


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 WikiHomePage

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

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(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 alos: this GoodStyle page.

?Anchor(pages)

Article

?Anchor(pages-name)

URL / page naming convention

?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 :

See also: ["HelpOnPageCreation"].

?Anchor(rename)

Rename a page

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.

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

  • [#pages-name Choose a name for a page].
  • 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.

  • X-( 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)

  • translation consideration : delete translated pages too !

?Anchor(merge-and-split)

Merging and Splitting pages

It's a good idea, Your are encouraged to :

?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: ["HelpOnProcessingInstructions"].

?Anchor(article-header)

  • Try to attach your page to the appropriate portal
  • 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)

  • Footer is optinal
  • Insert [#categories Categories] for relationnal structure
  • Insert a section like "See also" for transversal links.
  • Insert [#tags tags]
  • Refer to DefaultTemplate to respect the way

?Anchor(discussion)

URL for Discussion

  • Each banner could include a discussion link like:

    (!) [:/Discussion:Discussion]

 (!) [:/Discussion:Discussion]

  • This Discussion link is optionnal. Use it only when needed.
  • See ["DefaultTemplate"] if necessary

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)]]||

?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(tags)

Tags

Warnings

?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: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(portal)

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)

Naming

  • Portal naming is identical like article naming convention

?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)

Define article as portal

If you want your article page becomes a portal page, follow instructions below:

?Anchor(portal-idb)

Image Data Base

You can centralize icone and logo of portals to ["Portal/IDB"]. It's useful for translated portal and to have homogeneous artwork.

?Anchor(links)

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"

See also: ["HelpOnLinking"]

?Anchor(internal-links)

Internal Links (within this wiki)

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

  2. [:SomeParentPagewith/FooPage:FooPage] is frequently used to shorten sub pages.

  3. [: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 :

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

Image and Media

See also: ["HelpOnLinking"].

Credits and Copyright consideration
It's a good idea to 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" http://www.debian.org/logos/openlogo-100.jpg
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(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 :

  1. Use it.
  2. Put useful content in it (keep [:/Content#criteria:Content Criteria] in mind).
  • When someone ask a question in a mailing list, forum, irc channel :
    1. Point him/her to official Debian document (www.debian.org/* , man page, README, etc.) best ?BR suggest improvement to author or maintainer if needed.?BR?BR or

    2. update the appropriate wiki page to make sure it answers his/her question, then point him to the page. 2nd best choice

?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 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

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)

Technical Information

ToDo: write this paragraph

  • moinmoin Software.

?Anchor(complex-formating)

Advanced Formating / Complex Formating

AVOID using advanced formating using table, include, etc.

?Anchor(translation)

Translations

  • <!> 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:

?Anchor(translation-synchronize)

Synchronise contents

Some recommendations :

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

?Anchor(helping)

Helping wiki.debian.org

Everyone can help improving wiki.debian.org :

  • 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)
  • Translating pages.
  • Transmit your knowledge (How do 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 at work, explain your problems an needs.

Debian also need non-IT skills (legal ; marketing ; organising events ; press relation and much more ; fund raising)

?Anchor(faq)

Frequently Asked Questions

Where can I help ?

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

Wiki Policy Approbation System

For important subject and, if discussion can't stabilized, you can propose a [:?DebianWiki/WikiVote:wikivote] as resolution.