Differences between revisions 5 and 6
⇤ ← Revision 5 as of 2007-10-13 19:24:19 →
Size: 10794
Editor: FranklinPiat
Comment: add FAQ section from "About" page.
← Revision 6 as of 2007-10-14 12:13:30 → ⇥
Size: 11611
Editor: FranklinPiat
Comment: suggest using HomepageTemplate and many improvements.
Deletions are marked like this. Additions are marked like this.
Line 28: Line 28:
''Some ideas for your home page, grabbed from various existing home pages.'' ''You can use the ''Homepage``Template'' when you create your homepage. Here are ideas for your home page, grabbed from various existing home pages.''
Line 115: Line 115:
== Internal Link == == Internal Links ==
Line 122: Line 122:
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]}}}. 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]}}}.
Line 126: Line 126:
External Links (to and from external sites, ["InterWiki"], etc....)

The preferred way to link to external ressources is :		 External Links (to external sites, ["InterWiki"], etc....)

The preferred way to link to external resources is :
Line 133: Line 133:
(avoid the notation {{{ [http://www.foo.com link label] }}} because the target is obscure for visitors.) (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].")
Line 145: Line 145:
 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.  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
}}}
Line 171: Line 175:
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. 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.
Line 176: Line 180:
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). 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]).
Line 179: Line 183:
= Keeping track of changes. = = Keeping track of changes =
Line 181: Line 185:
 * Page History
 * User contributions
 * Subscribe to pages		  * The List of '''recent changes''', anywhere on this wiki, click the "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 [[GetInfo(UserPreferences)]]).
Line 201: Line 206:
Wiki page Creation, Deletion/removal, naming, renaming, merging, splitting are explained in a separate page :
 * ["../WikiPage"]

##do not link to this anchor, link to DebianWiki/Translation directly !		 Wiki page Creation, Deletion/removal, naming, renaming, merging, splitting are explained in [:../WikiPage:../WikiPage].

##do not link to this anchor, link to DebianWiki/TranslationGuide directly !
Line 207: Line 211:
A Wiki page Translation guide is explained in a separate page :
 * ["../Translation"] of wiki pages (naming page ; synchronize with other languages).		 A Wiki page [:../TranslationGuide:Translation guide] (naming page, synchronize with other languages and more).
Line 212: Line 215:

 I would like a more structured Debian wiki, without orphan articles :: Structure is overrated. See [http://c2.com/cgi/wiki?LimitsOfHierarchies]

 I can see a list of '''all''' pages ? :: ["TitleIndex"]
Line 222: Line 221:
  * Search [:BackLink:backlinks] to ["HelpWanted"], ["FixMe"] and ["ToDo"].
  * Search [:BackLink:backlinks] to ["HelpWanted"], ["FixMe"] and ["ToDo"].
``
 I can see a list of '''all''' pages ? :: ["TitleIndex"]

 I would like a more structured Debian wiki, without orphan articles :: Structure is overrated. See [http://c2.com/cgi/wiki?LimitsOfHierarchies]

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

Translation(s): none

[:?DebianWikiConventionsDiscussion#editor-guide:Discussion]||

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

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

  • 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

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

External Links (to external sites, ["InterWiki"], etc....)

The preferred way to link to external resources is :

An alternate option 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].")

?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

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

  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 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 ["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 "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 ?GetInfo(UserPreferences)).

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

  • It's difficult to understand and maintain for you and other wiki editors.

  • It's difficult to read the diff of complex formatings.

?Anchor(pages)

Pages

Wiki page Creation, Deletion/removal, naming, renaming, merging, splitting are explained in [:?../WikiPage:?../WikiPage].

?Anchor(translation)

Translations

A Wiki page [:?../TranslationGuide:Translation guide] (naming page, synchronize with other languages and more).

?Anchor(faq)

Frequently Asked Questions

Where can I help ?

I can see a list of '''all''' pages ?

["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.