Talk:Community Updates/Draft

From Openmoko

< Talk:Community Updates(Difference between revisions)
Jump to: navigation, search
(Mailing list interface: =discuss)
(moving guidelines to Openmoko Wiki Editing Guidelines)
Line 3: Line 3:
  
 
==Guidelines==
 
==Guidelines==
Conform to [[Openmoko_Wiki_Editing_Guidelines]]. These guidelines covers most of uncertain cases an editor might run into while editing wiki pages. It takes half an hour to dig through this, but is worth to do it at least summarily.
+
Conform to [[Openmoko Wiki Editing Guidelines]]. These guidelines covers most of uncertain cases an editor might run into while editing wiki pages. It takes half an hour to dig through this, but is worth to do it at least summarily.
  
 
==Editing==
 
==Editing==
 
Conform to [[Help:Editing]]
 
Conform to [[Help:Editing]]
 
==Templates==
 
Conform to [[Templates]]. Especially when it comes to handy Semantic boxes, like Template:ApplicationBox:<BR>
 
<pre><nowiki>
 
{{ApplicationBox|
 
Name=[[Gpe-FileManager]]|
 
Description=A file manager application with MIME types and remote access support from the the GPE Palmtop Environment (GPE) project.|
 
Screenshot=Gpe-filemanager.png|
 
Homepage=http://gpe.linuxtogo.org|
 
TestedOn=Om2008.8|
 
PackageName=gpe-filemanager
 
}}
 
</nowiki></pre>
 
If application/something else has its own wiki page, put its name in double square brackets:
 
 
==Links==
 
Keep in mind the difference between [http://meta.wikimedia.org/wiki/Help:Link#Interwiki_links internal] and [http://meta.wikimedia.org/wiki/Help:Link#External_links external] links. Try to use them properly, accordingly to their destination
 
 
==Date format==
 
Dates in article body text should all have the same format. Use one standarized date format. Current version of media wiki software is {{CURRENTVERSION}}. When it will be 1.15+ we can use unified date format, which would be represented accordingly to predefined user's preferences, while showing some default format for not registered users. (Is there any chance for upgrading this wiki version?) Here is nice example of [http://www.mediawiki.org/wiki/Help:Variables#Formatting date formating]
 
 
You might wonder wich date format to choose? Many will say: 'use "DD, month YYYY" because it is easy to read for human'. But I say it is easy to read only for those humans born in UK or USA. For the rest of world, people's brain has to do additional task of translating english_month's_name into your local_month's_name. Another argument of mine is that there are plenty of countries where official date format is YYYY-MM-DD, MM-DD-YYYY or else. So, how to achieve consensus? Answer is simple: use international [http://en.wikipedia.org/wiki/ISO_8601 ISO_8601] standard. In short it says:
 
 
''"The signature feature of ISO 8601 date and time representations is the ordering of date and time values from the most to the least significant or, in plain terms, from the largest (the year) to the smallest (the second)."''
 
 
Thus, as a conclusion, official date format for Community updates should be '''YYYY-MM-DD'''. Additionally this is most natural format for sorting purposes.
 
 
==Filling "Edit Summary" field==
 
Many wiki editors do not fill in "Edit Summary" filed under "edit" box. This summary becomes very handy when it comes to later version comparision. Always fill in "edit summary" field when editing wiki pages. All you need to type there are 3~4 words of comment, and really makes life easier for wiki administrators.
 
 
It's a good idea to set your user preferences (under Editing) to "Prompt me when entering a blank edit summary". If you really want to keep it empty, you can just confirm the message or enter a blank space to avoid the message.
 
 
It is also quick and quite good habit to prefix summary with +/-/= depending upon you add/delete/edit content.
 
  
 
==Creating new templates==
 
==Creating new templates==
Line 81: Line 48:
 
:::I just had a look through the wiki and most links are pointing at individual messages rather than an entire thread. But if it is so important not to have people post through web interfaces we can recommend the "subject" link as well. -- [[User:Marko Knöbl|Marko Knöbl]] 15:52, 28 August 2009 (UTC)
 
:::I just had a look through the wiki and most links are pointing at individual messages rather than an entire thread. But if it is so important not to have people post through web interfaces we can recommend the "subject" link as well. -- [[User:Marko Knöbl|Marko Knöbl]] 15:52, 28 August 2009 (UTC)
 
::I opt in letting them browse one full thread.--[[User:Leadman|LeadMan]] 12:00, 31 August 2009 (UTC)
 
::I opt in letting them browse one full thread.--[[User:Leadman|LeadMan]] 12:00, 31 August 2009 (UTC)
 
==Community Update releasing process==
 
And last but not least...In fact it is pretty important: never copy/paste contents of CU to release the page! Instead always use "move" button on top of wiki page. This "button" is intended for this action and by using it you save all editions and contributions history.
 

Revision as of 13:33, 8 September 2009

Contents

Welcome

Here you can get a clue on how to contribute to Community updates, while conforming to wiki editing guidelines. You can take a look at Community_Update_Draft, to have a feel how coming update draft would look like, if we follow all these standarised wiki guidelines. Feel free to discuss here about this topic, maybe we achieve consensus before next CU. Everybody is welcome to help. Following are main topics which should be covered.

Guidelines

Conform to Openmoko Wiki Editing Guidelines. These guidelines covers most of uncertain cases an editor might run into while editing wiki pages. It takes half an hour to dig through this, but is worth to do it at least summarily.

Editing

Conform to Help:Editing

Creating new templates

Using Template:ApplicationBox is great idea! Why not create similar templates for other parts of CU? The disadvantage of this way would be little more code to fill, but all entries in particular part of CU would have similar layout. Following this idea Template:DistributionBox is currently being developed. You can see preview on Community_Update_Draft in Distribution section.

  • Currently there is voting ongoing on community mailing list. Come on in and vote for your favourite template, or leave comment here!

Mailing list interface

Often there is a need to provide link pointing to discussion on a mailing list. Services providing web interface to mailing lists (like nabble.com) were reported many times to break discussion threads in mail clients. Remember, mailing lists were designed to be used with mail clients, not with web forums. If you need to provide link to discussion on mailing list for those who are not subscribed, use mailing list archives.

There were always problems with links to the mailing list archive, because the posts these links are referring to seem to change frequently and these links become outdated. For example see the refereces section of the Wikipedia article on Openmoko. References 9, 10 and 16 are now linking to completely different topics. That's why I think it is better to link to other archives which do not change the URLs. I think Markmail looks good. Can I change this guideline?--Marko Knöbl 15:05, 24 August 2009 (UTC)
Hi Marko,
Are you sure that http://lists.openmoko.org/pipermail/community/ changes URL also? It looks like it is "Pipermail" ,and I didn't hear it had such a problems in the past. I looked at Markmail, and found it really non-friendly :(. Maybe there are other services you might suggest? Regardles of the above please prepare here instruction like mine and we will test it, ok? --LeadMan 12:16, 25 August 2009 (UTC)
The Wikipedia references I cited are all from pipermail. For further examples see the community updates from April 05, section "Distributions".
The only practical way to find a certain topic on the Markmail archives is by using the search function, so the instructions would be: go to openmoko.markmail.org and enter the thread's title into the search bar. Once you found the right thread there is a list of messages from which you can select the right one.
Concerning other services: The only other alternative I know is gname. It has a posting interface too, but that's more hidden than at nabble. --Marko Knöbl 10:35, 26 August 2009 (UTC)
I have tested 'gname' for about 5 minutes and already like it :). It is much more intuitive, allows to show single thread, and a lot of faster than MarkMail, which is still loading in my FireFox. Areyou sure this service do not sufferissues like nabble? In the meantime lets make a draft:

Often there is a need to provide link pointing to discussion on a mailing list. Services providing web interface to mailing lists (like nabble.com) were reported many times to break discussion threads in mail clients. Remember, mailing lists were designed to be used with mail clients, not with web forums. If you need to provide link to discussion on mailinglist for those who are not subscribed, use mailing list archives.

  • Go to gname
  • choose a mailing list
  • From top panel choose a post (preferably the one on the top of a thread)
  • At bottom panel click "Subject:" link
  • Copy URL from your browser into Community Update

(markmail loaded after ~7 minutes) Marko, do we need examples of post like with previous instruction? Feel free to fix what you do not like and commit changes.

P.S. It was rather easy to find posting functionality. --LeadMan 14:52, 27 August 2009 (UTC)

As I don't know anything about the issues of nabble I can't say if they occur at gname. Concerning the instructions: I'd rather recommend clicking "Direct link:" at the bottom instead of "subject:" --Marko Knöbl 12:49, 28 August 2009 (UTC)
Isn't it better to let them read all thread? "direct link" at the bottom, has much more visible "Posting" link on the left and we want to avoid posting through web services, right?--LeadMan 14:03, 28 August 2009 (UTC)
I just had a look through the wiki and most links are pointing at individual messages rather than an entire thread. But if it is so important not to have people post through web interfaces we can recommend the "subject" link as well. -- Marko Knöbl 15:52, 28 August 2009 (UTC)
I opt in letting them browse one full thread.--LeadMan 12:00, 31 August 2009 (UTC)
Personal tools

Welcome

Here you can get a clue on how to contribute to Community updates, while conforming to wiki editing guidelines. You can take a look at Community_Update_Draft, to have a feel how coming update draft would look like, if we follow all these standarised wiki guidelines. Feel free to discuss here about this topic, maybe we achieve consensus before next CU. Everybody is welcome to help. Following are main topics which should be covered.

Guidelines

Conform to Openmoko_Wiki_Editing_Guidelines. These guidelines covers most of uncertain cases an editor might run into while editing wiki pages. It takes half an hour to dig through this, but is worth to do it at least summarily.

Editing

Conform to Help:Editing

Templates

Conform to Templates. Especially when it comes to handy Semantic boxes, like Template:ApplicationBox:

{{ApplicationBox|
Name=[[Gpe-FileManager]]|
Description=A file manager application with MIME types and remote access support from the the GPE Palmtop Environment (GPE) project.|
Screenshot=Gpe-filemanager.png|
Homepage=http://gpe.linuxtogo.org|
TestedOn=Om2008.8|
PackageName=gpe-filemanager
}}

If application/something else has its own wiki page, put its name in double square brackets:

Links

Keep in mind the difference between internal and external links. Try to use them properly, accordingly to their destination

Date format

Dates in article body text should all have the same format. Use one standarized date format. Current version of media wiki software is 1.19.22. When it will be 1.15+ we can use unified date format, which would be represented accordingly to predefined user's preferences, while showing some default format for not registered users. (Is there any chance for upgrading this wiki version?) Here is nice example of date formating

You might wonder wich date format to choose? Many will say: 'use "DD, month YYYY" because it is easy to read for human'. But I say it is easy to read only for those humans born in UK or USA. For the rest of world, people's brain has to do additional task of translating english_month's_name into your local_month's_name. Another argument of mine is that there are plenty of countries where official date format is YYYY-MM-DD, MM-DD-YYYY or else. So, how to achieve consensus? Answer is simple: use international ISO_8601 standard. In short it says:

"The signature feature of ISO 8601 date and time representations is the ordering of date and time values from the most to the least significant or, in plain terms, from the largest (the year) to the smallest (the second)."

Thus, as a conclusion, official date format for Community updates should be YYYY-MM-DD. Additionally this is most natural format for sorting purposes.

Filling "Edit Summary" field

Many wiki editors do not fill in "Edit Summary" filed under "edit" box. This summary becomes very handy when it comes to later version comparision. Always fill in "edit summary" field when editing wiki pages. All you need to type there are 3~4 words of comment, and really makes life easier for wiki administrators.

It's a good idea to set your user preferences (under Editing) to "Prompt me when entering a blank edit summary". If you really want to keep it empty, you can just confirm the message or enter a blank space to avoid the message.

It is also quick and quite good habit to prefix summary with +/-/= depending upon you add/delete/edit content.

Creating new templates

Using Template:ApplicationBox is great idea! Why not create similar templates for other parts of CU? The disadvantage of this way would be little more code to fill, but all entries in particular part of CU would have similar layout. Following this idea Template:DistributionBox is currently being developed. You can see preview on Community_Update_Draft in Distribution section.

  • Currently there is voting ongoing on community mailing list. Come on in and vote for your favourite template, or leave comment here!

Mailing list interface

Often there is a need to provide link pointing to discussion on a mailing list. Services providing web interface to mailing lists (like nabble.com) were reported many times to break discussion threads in mail clients. Remember, mailing lists were designed to be used with mail clients, not with web forums. If you need to provide link to discussion on mailing list for those who are not subscribed, use mailing list archives.

There were always problems with links to the mailing list archive, because the posts these links are referring to seem to change frequently and these links become outdated. For example see the refereces section of the Wikipedia article on Openmoko. References 9, 10 and 16 are now linking to completely different topics. That's why I think it is better to link to other archives which do not change the URLs. I think Markmail looks good. Can I change this guideline?--Marko Knöbl 15:05, 24 August 2009 (UTC)
Hi Marko,
Are you sure that http://lists.openmoko.org/pipermail/community/ changes URL also? It looks like it is "Pipermail" ,and I didn't hear it had such a problems in the past. I looked at Markmail, and found it really non-friendly :(. Maybe there are other services you might suggest? Regardles of the above please prepare here instruction like mine and we will test it, ok? --LeadMan 12:16, 25 August 2009 (UTC)
The Wikipedia references I cited are all from pipermail. For further examples see the community updates from April 05, section "Distributions".
The only practical way to find a certain topic on the Markmail archives is by using the search function, so the instructions would be: go to openmoko.markmail.org and enter the thread's title into the search bar. Once you found the right thread there is a list of messages from which you can select the right one.
Concerning other services: The only other alternative I know is gname. It has a posting interface too, but that's more hidden than at nabble. --Marko Knöbl 10:35, 26 August 2009 (UTC)
I have tested 'gname' for about 5 minutes and already like it :). It is much more intuitive, allows to show single thread, and a lot of faster than MarkMail, which is still loading in my FireFox. Areyou sure this service do not sufferissues like nabble? In the meantime lets make a draft:

Often there is a need to provide link pointing to discussion on a mailing list. Services providing web interface to mailing lists (like nabble.com) were reported many times to break discussion threads in mail clients. Remember, mailing lists were designed to be used with mail clients, not with web forums. If you need to provide link to discussion on mailinglist for those who are not subscribed, use mailing list archives.

  • Go to gname
  • choose a mailing list
  • From top panel choose a post (preferably the one on the top of a thread)
  • At bottom panel click "Subject:" link
  • Copy URL from your browser into Community Update

(markmail loaded after ~7 minutes) Marko, do we need examples of post like with previous instruction? Feel free to fix what you do not like and commit changes.

P.S. It was rather easy to find posting functionality. --LeadMan 14:52, 27 August 2009 (UTC)

As I don't know anything about the issues of nabble I can't say if they occur at gname. Concerning the instructions: I'd rather recommend clicking "Direct link:" at the bottom instead of "subject:" --Marko Knöbl 12:49, 28 August 2009 (UTC)
Isn't it better to let them read all thread? "direct link" at the bottom, has much more visible "Posting" link on the left and we want to avoid posting through web services, right?--LeadMan 14:03, 28 August 2009 (UTC)
I just had a look through the wiki and most links are pointing at individual messages rather than an entire thread. But if it is so important not to have people post through web interfaces we can recommend the "subject" link as well. -- Marko Knöbl 15:52, 28 August 2009 (UTC)
I opt in letting them browse one full thread.--LeadMan 12:00, 31 August 2009 (UTC)

Community Update releasing process

And last but not least...In fact it is pretty important: never copy/paste contents of CU to release the page! Instead always use "move" button on top of wiki page. This "button" is intended for this action and by using it you save all editions and contributions history.