Differences between revisions 16 and 17
Revision 16 as of 2007-10-12 21:50:41
Size: 19578
Comment:
Revision 17 as of 2007-10-12 22:33:46
Size: 19599
Comment:
Deletions are marked like this. Additions are marked like this.
Line 258: Line 258:
<!> Redundant pages ([[Date]]): [:ARedundantPage:A redundant page], [:AnotherRedundantPage:Another Redundant Page] }}} <!> [:CategoryRedundant:Redundant pages] ([[Date]]): [:ARedundantPage:A redundant page], [:AnotherRedundantPage:Another Redundant Page] }}}

FrontPage > ?DebianWikiAdministration > ?DiscussionsStarter > Debian Wiki Conventions Discussion

?TableOfContents(4)

Please sign your comments using @SIG@.

Articles

?Anchor(pages-names)

URL / page naming convention

We should come up with a semi-official convention for page naming. Apparently there are a handful of contributors who have a long term view of what the wiki should look like, but each seems to be working in his/her corner. The result is kind of a mess.

Some page are named using the camel case, like this one (?DebianWikiConventionsDiscussion). Others use an underscore like all the links in this page: ["Portal_Welcome"]. Some page are only a single word, like ["About"].

We should come up with a convention. What is the advantage of using one rather than the other? -- AugustinMa ?DateTime(2007-10-08T10:01:05Z)

  • I think comprehensible page naming is very important. Readers appreciate clear name. So I prefer break up sentences and contract them. I recommended to get a user-friendly apporach. It's necessary to have short name, not a big sentence. Underscore must be used than white space. White spaces are not recommended in the URL.?BR

  • Example of Page naming for "How to configure ATI driver to active 3D support":

    • Example #1: HowToATI3D

    • Exemple #2 (I think more comprehensive): ["Howto_ATI_3D"]

    • Counter-example: ["How to configure ATI driver to active 3D support"]

    • For link, I recommend some thing like: [:Howto_ATI_3D:How to configure ATI driver to active 3D support]?BR

    -- SalokineTerata ?DateTime(2007-10-10T21:57:29Z) Regarding page naming, we have to take in consideration that we use moinmoin. We shouldn't use columns (:) because this would break [:page:name: title]. Like many user who have used mediawiki, i used to prefer space or underscores in page name. however, it isn't how moinmoin expect to work, so I switch to the wiki.debian.org de-facto standard i.e use WikiName. -- FranklinPiat ?DateTime(2007-10-10T23:53:24Z)

Use of CamelCase

This wiki is based on MoinMoin, which makes it easy to use CamelCase to create links and new pages. However, the page ["Portal_Welcome/Discussion"] suggests we use words separated by underscores (like_this instead of ?LikeThis). I don't particularly like ?CamelCasedTitles but it is easier to use them and people will use them regardless of what we decide. This is an important decision to make before we go too far in organizing the wiki. Your comments are welcome here. -- AugustinMa ?DateTime(2007-10-09T04:47:10Z)

As you, I don't like particulary CamelCasedTitled. I prefer naming conventions [http://en.wikipedia.org/wiki/Help:Page_name like Wikipedia]. -- SalokineTerata ?DateTime(2007-10-10T21:57:29Z)

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:08:49Z)

  • Concise title
  • Can using underscore "_" to separte words
  • Can using CamelCase

  • Each word start with uppercase
  • Don't use these characters:two points  : , semicolon  ; , space  " " , backslash  \ , accents  é à ö ñ ..., apostrophe  ' 

  • Using slash can be use to group same pages
  • Translated pages finished with the name of Language (place side by side)

?Anchor(discussionspages)

URL for Discussion page convention

Same as above: there is a lack of consistency. Some discussion pages like this one are named using the camel case (?DebianWikiConventionsDiscussion). Other pages use a slash (.../Discussion), like ["FrontPage/Discussion"]. Which standard to use? -- AugustinMa ?DateTime(2007-10-08T10:01:05Z)

Something lile [:/Discussion:Discussion] is easy to use with templates or when you copy and paste contents. Relative path are more flexible. I recommend to integrate this link in the default banner to invite readers for discussion.

  • Example: (!) [:/Discussion:Discussion]

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:08:49Z)

  • Each banner include a discussion link like:

    (!) [:/Discussion:Discussion]

 (!) [:/Discussion:Discussion]

?Anchor(portals)

Portal concept

URL / Portals naming

?Anchor(portals-names)

  • For Portals, it's different. It must differciate than articles. I prefer a strict convention clear and condensed with underscore or ":".?BR

  • Example of Portal naming for "Portal of how to install and configure your Webcam":

    • Example #1: ["Portal_Webcam"]

    • Example #2 (why not [http://en.wikipedia.org/wiki/Portal:List_of_portals like Wikipedia] ? but not very compatible with Moinmoin): ["Portal:Webcam"]

    • Counter-example #1: PortalWebcam

    • Counter-example #2: PortalHowToWebcam

    • Counter-example #3: Portal_HowTo_Webcam

    • For link, I recommend some thing like: [:Portal_Webcam:Webcams]

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:08:49Z)

  • Using separated words with underscore
  • Translated portal have a translated title Portal_Hardware / Portail_Materiel 

  • When translated page is modified, synchronize english version (if you can't, notify discussion english page)

Management understanding reader level

?Anchor(portal-reader-level)

The Portal Welcome is composed in 4 global parts. Each part aggregate other portals by knowledge level. Language using in article must be adapt to reader level. You can differentiate knowledge level like this:

  • Beginner: Someone who don't know any thing about Linux, who don't know what is Debian and can have an overview of what is Windows. Articles must be written in no-technical language. This is a beginner in general concept of informatic.
  • User: Someone using only graphic tools. All computing words must be explain for example with a Wikimedia link. Abbreviations are explained too. So, an article characterized User level is basically based on GUI tools (Graphic User Interface)

  • Advanced user: Someone who understand effectiveness of a shell or want to use Debian as server. Language must be informatic and contained official links or homepages. So, an article characterized Advanced User level is basically based on CLI tools (Command Line Interface).

  • Developer/Contributor: Who want to contribute to Debian project. Language is technical and defined. Reader must know himself how to search more informations. Source code and programming languages are get onto.

Knowledge level indicator of article

?Anchor(level) All articles attached to a portal must indicate its knowledge level at its top. Normally, You have just to take the same level of attached portal. This indicator is symbolized by star items:

  • {o} {o} {o} Beginner

  • {*} {o} {o} User

  • {*} {*} {o} Advanced user

  • {*} {*} {*} Developer/Contributor

Ready to paste:

 {o} {o} {o} ''Beginner''
 {*} {o} {o} ''User''
 {*} {*} {o} ''Advanced user''
 {*} {*} {*} ''Developer/Contributor''

As suggesting Franklin, articles can't be always classified in this point of view. To go in his way, I recommend to use these indicators only for Portals pages.

Each parts of portals must be guide the readers. By example, Portal_Shells is classified Advanced user, but at first, this portal must explain what is a shell and the basic howto. Next, real' howto can be presented. Other example, Portal_Developer (classified Developer/Contributor) must present official references, debian.mentors, your first package howto ...etc and all of what you want when you would like to become a new developer.

Maybe we can rename this four levels as Beginner, User, Administrator and Developer ? -- SalokineTerata ?DateTime(2007-10-10T21:57:29Z)

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:08:49Z)

  • Don't using indicators, just understanding how to write the article and what language level to use
  • main portal is composed in four domain: Beginner, User, Administrator and Developer

  • Each attached articles must be wrotten according in agreement with understanding level of its portal.
  • Possibly to warn about level content only in discussion page, not directly on the article (too aggressive method). Warnning is for authors, not readers.

?Anchor(links)

A portal contain only links ... and just that. It's like a switching system. Links must be written and translated without to show wiki syntax.

  • Example: [:ThisIsCorrectLink:This is a good link for an example]

  • Counterexample: ?ThisIsCorrectLink - This is not a good presentation of this link.

If your link point to article written in other language that your native language, indicate it at the end of the link.

  • Example: [:DebFrWifi:Installation and configuration of Wifi card] (in french)

An helpful description, understandable and concise.

  • Example: Don't refer to X System when it's not needed
  • Exemple: Not Debian word anywhere. We know that we will talk about Debian on this Wiki. We are not going to speak about Redhat.

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:08:49Z)

  • Links are composed like: [:TitlePage:Understandable and concise description]

  • Not native language links finish with destination language: ''(in french)'' or ''(en anglais)''

Is it the official portal of Wiki Debian ?

Yes and No !

This set of page comes from user's initiative as you. Portals can be considered as official because there are on Debian Wiki. On other hand, the official page assembled information of the Wiki is the ["FrontPage"]. In brief, it's not the most important question. The real question is: Is this portal answer to my needs ? If you reply No ... you can contribute to improve it. If you reply Yes, speak well of it.

Portal concept must be more stable, more hold and more translated. Next, maybe we can update the frontpages ?

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:08:49Z)

  • "Portal_Welcome" will be renamed "?FronPage/PortalProposal". It's more understandable

  • To prepare the update of frontpage, all pathes in banner don't must integrate "Portal_Welcome" but "?FronPage" pages as root page

  • When Portals will be stabilized, we come back here to validate the beginning of the frontpage update

?Anchor(banner)

Banner

Articles don't have real imposition in their forms. Just some informations are strongly recommended.

  • A knowledge level indicator (see section Knowledge level indicator of article)

  • A path named Fil d'Arianne: The path broswed to come on current article. ["FrontPage"] > Portal Welcome ?BR ["FrontPage"] > ["Portal_Welcome"] > A Page ?BR ["FrontPage"] > [:Portal_Welcome:...] > ["A_Page"] > Discussion

    • {i} note: In this example, the name of pages will be:

       "FrontPage"
       "Portal Welcome"
       "A_Page"
       "A_Page/Discussion"
  • A link to Discussion. Just the link, the page will be created if needed.
  • If this page have some translations, you must indicate them, it's very important. You can, if you are capable, synchronize your version. English version is the swivel page. If someone do an update in a translated page, he must synchronizes it with english version or to notify this update in the english discussion page. I don't really like ".." because i dont't where i would end up if i click it. I assume that if the lines because too long, it's because the path from the top is too long. -- FranklinPiat ?DateTime(2007-10-10T23:53:24Z)

Supplementary recommendations about portals

Portal ["Portal_Introduction"] play a part of template. Use it to create a new portal easily.

Besides preceding recommendations, portal pages must be named like:Portal + _ + Title of portal.

  • Example, the french portal talking about hardware is named Portail_Materiel

  • Example, the english portal related to softwares is named Portal_Software

They must contain:

  • The same banner like using on ["Portal_Introduction"]
  • A short portal description starting an icon which is symbolized it. This icon must be relevant and to assert perfectly the portal.
  • A list of links pointing to articles or sub-portals.
  • All portals must be attached like a tree.

Supplementary recommendations about articles

  • Try to write your article in accessible language for user the less expert. In article tagged Beginner level, this recommendation in obligatory.

  • Try to give two method: a GUI version for User level and a CLI version for Advanced User level.

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:08:49Z)

  • Portals banners includes:
    • Path like: [:FrontPage:Frontpage] > [:Portal_AThing:A thing] > Current Portal

    • Indicate translation links
    • Insert Discussion link
  • Article banner includes:
    • Try to attach your page to a portal page
    • 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 case must be attached

    • Indicate translation links (very important to search if exist!)

    • Insert Discussion link
  • Refer to DefaultTemplate to respect the way

Footer

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:44:25Z)

  • Footer is optinal
  • Insert Categories
  • Insert a section like "See also" for transversal links.
  • Insert tags
  • Refer to DefaultTemplate to respect the way

Warning

If you find redundant articles, please, insert this flag at the top of the page:

Redundant : This article contain redundant information.?BR Please, merge it with ["Name_of_the_other_article"].

  • I Think it isn't important for the visitor, when he/she starts reading the page, to known that the page duplicates the content of another one. So we don't need to put a big colored warning : We could put a simple link at the bottom of the page, so if a user actually don't find the answer, he/she can carry-on on another page. -- FranklinPiat ?DateTime(2007-10-10T23:53:24Z)

  • Ready to paste:

{{{||<tablestyle="width:65%;margin-left:35%;padding-left:30pt" style="border:1pt solid #b48;border-left:5pt solid #d4a">Redundant : This article contain redundant information.?BR Please, merge it with ["Name_of_the_other_article"].|| }}}

If you find an article without enough information, please, insert this flag at the top of the page:

Not enough content : This article have not enough content.?BR Please, improve it or merge it in an article having the same goal.

  • I Think it isn't very important for the visitor, when he/she starts reading the page, is incomplete. it's still a good idea warn him/her. we could simply use  /i\ This article have not enough content.... AND tag the page with FixMe -- FranklinPiat ?DateTime(2007-10-10T23:53:24Z)

  • Ready to paste:

{{{||<tablestyle="width:65%;margin-left:35%;padding-left:30pt" style="border:1pt solid #b48;border-left:5pt solid #d4a">Not enough content : This article have not enough content.?BR Please, improve it or merge it in an article having the same goal.|| }}}

Portals are good tools to identify redundant articles. If you find its, finish link with this simley X-( X-(

  • Example:
    • [:DebianIntroduction:Introduction of Debian], [:Debian Introduction:Another introduction of Debian] X-(

-- SalokineTerata ?DateTime(2007-10-10T21:57:29Z)

Policy suggestion #1

-- SalokineTerata ?DateTime(2007-10-11T21:44:25Z)

  • Don't tag at the bottom of the page. Warning tag is for authors, not for readers
  • Insert tag on the footer page
  • Tag must be less aggressive looking like:
    • <!> [:CategoryRedundant:Redundant pages] ([[Date]]): [:ARedundantPage:A redundant page], [:AnotherRedundantPage:Another Redundant Page] 
  • Page without enough content can be directly merging or remove
  • When you merge a page, sometimes, it's right to keep dead page and convert it as a redirection #redirect MergingPage (Optional)

?Anchor(editor-guide)

Debian Wiki /Editor Guide

Could you have a look at ["DebianWiki/EditorGuide"] : Contributions (there) & Feedback (here) are welcome.

Thanks, -- FranklinPiat ?DateTime(2007-10-10T23:58:26Z)

Very good job ! -- SalokineTerata ?DateTime(2007-10-11T21:44:25Z)


?Anchor(translations)

Pages Translations

  • PaoloPan had started a discussion thread about translations on [:?WikiMeta#translation:WikiMeta] a while ago. Shouldn't we have that discussion about translation on that page ?

  • I have written the ["DebianWiki/Translation"], based on the current practices i have observed on this wiki. (I haven't included Salokine's proposal... since it's a proposal. The page will have to be updated once there's a standing position.).
  • FYI, we might want to ask for advices about translations to some experienced people :

-- FranklinPiat ?DateTime(2007-10-11T23:52:57Z)

Another problem are translated pages, there's no convention used (check the FrontPage translations for an example). There's been talk about the lack of proper i18n support in MoinMoin, like the checks for outdated translations that the current Debian website is doing.GuillemJover

  • I find it a bit messy to combine all the languages in one wiki. The ideal would be to have one sub-site for each language, either something like en.wiki.debian.org/ or wiki.debian.org/en/. But this would require more work from the [?DebianWikiAdministrators administrators] to keep the system up to date, etc. I don't know what the second best solution would be, but it's worth discussing. Maybe we could have the language tag (Fr, De...) as part of the page name like this: ?FrSomePageInFrench, ?DeSomePageInGerman, etc. -- AugustinMa ?DateTime(2007-10-09T04:05:04Z) I prefer to finish the name by the translating language. It's easy to find translating pages like:

  • ["Debian"]

  • ["DebianFrench"]

  • ["DebianGerman"]

  • ["DebianRussian"] When using the FindPage, all translations are grouped. -- SalokineTerata ?DateTime(2007-10-10T21:57:29Z)

    Like [:?DebianWikiConventionsDiscussion#links:here], can we change in

     Linking
     
     Linking to the same page, in other language, see Page header below. 
     Links to non translated page should be prefixed by [en].
    to: Links to non translated page should be follow by: (in destination language)

    ?BRExample:

  • [:DebianReleases:Les versions de Debian] (en anglais)

  • [:DebFrAmiloM:Some improvements for Fujitsu-Siemens laptop] (in french)

    Bye.?BR -- SalokineTerata ?DateTime(2007-10-12T19:23:10Z)