Conventions

From OLPC
Revision as of 01:25, 4 January 2009 by Skierpage (talk | contribs) (comment on this, contrast with OLPC:Style guide)
Jump to navigation Jump to search

See OLPC:Style guide for general wiki conventions including Article (page) naming, Category tagging, etc. This page is more for shepherding proposed templates and conventions from proposal to reality. (And it doesn't follow the style guide in its Over Capitalization and use of h1 headings :-) )

Conventions help create organization within this wiki (http://wiki.laptop.org). These conventions include:

  • Category tagging and hierarchy
  • Template and Status Box use

The wiki is growing as the OLPC program becomes more popular and touches more lives. Conistency becomes helpful in aiding users find and compare similar information. This article collects proposals and records conventions in order to bring more consistency to the wiki in service of making it a more accessible and useful resource.

Conventions & Proposals

What's in a name? Why Conventions

This wiki hopes to be the main repository of information for the OLPC project. The wiki contains a large number of articles for overlapping audiences: the general public, developers, laptop users, educators, policy makers, and others. Information is gathered from the various communication channels and added into articles.

Some of the information resembles a database in its natural organization with details of related items set out in separate articles with similar layouts. The information often varies too much to use an identical layout or traditional database.

The Wiki Way emphasizes making information available. The first sources of information are often rough, even cut-and-paste from email conversations that contain a technical data point or a stub of basic information. Everyone can edit. Some readers wordsmith the prose to make it more readable. Others add a new link or some new information. A more passionate reader may clean-up, reorganize, and research an expanded article. There is no approval process: people just edit.

As the Wiki grows, conventions aid readers and contributors by making it easier for them find articles that share similar characteristics without imposing much burden on the article writers. For example, putting a [[Category:Keyboard]] tag into all articles related to keyboards helps everyone.

Adding a Proposal for Changes To Many Articles

Edits require more effort when a change will need to be made to more than a handful of articles. A reader may need skim many nearly identical articles, discover the real organization behind the articles, and then separately edit each article. A change in convention may need to be made on many existing articles and therefore potentially impacts many readers. More care and thought is required for such large-scale modifications than the wiki-standard WP:BRD for a single article edit.

The goal of these larger changes is to make wiki better for another round of growth. While the new changes need not be permanent solutions, they should be good enough for the next year. No one wants to constantly reorganize the wiki. Building a consensus and inviting comment in advance cuts down on effort in making changes.

To make a proposal, write it below. Add a note and link to the talk page of some of the proposed articles to alert those readers of the proposed change. Others may comment on your proposal, make improvements, discuss ideas, and try to build some consensus. Consider your proposal accepted once you have consensus or if about a week goes by with no new comments. Then move the proposal, removing discussions, into the accepted conventions. Then you make the necessary changes to all the articles. You should propose a change only if you are passionate enough about the change to do the work.

It is not generally necessary to discuss conventions that already show signs of being widely accepted on this wiki, many conventions developed by Wikipedia contributors have been adopted or adapted for use on this wiki and Wikipedia makes a useful reference for how similar situations are handled by a large group of collaborators.

Commenting on Proposals

Like any wiki-page, the text of the proposal is not sacred, it is on a wiki and open for thoughtful, well-intentioned edits. If you more-or-less agree with the proposal, but have minor improvements to make to the details, then just make the edits to the proposal text and add a brief comment in the Comments section. It is not necessary to write out a long argument in favor of a spelling correction or other small-scale edit that does not change the essence of the proposal. The proposer will be watching this page and is free to revert modifications to their proposal text if they feel they miss the point. It is the proposer's idea, so you shouldn't change it's fundamental argument; but they have posted it here for comments AND improvements.

Significant disagreement or a completely different take on how the proposed issue is best handled should definitely be addressed in the Comments section. If you have a better idea, you are free to draft your own competing proposal and post it here. Just remember that if your idea wins the debate on what is best practice for the OLPC wiki, you've pretty much signed on to implement it.

Proposed Changes

Put your proposed change here. A good proposal includes a title, date you wrote it, link to your user page, a well written convention for how future arguments are made along with examples, and a list of some of the pages affected.

Example Proposal

Here's an example proposal (these are not actual signatures, but it does paraphrase/dramatize a similar discussion):

Articles of Specific Keyboard Layouts by User:Cjl on April 8, 2008.
Keyboard Layouts To Be Named "OLPC language_name (language_code) Keyboard". For example, "OLPC Spanish (es) Keyboard". The language name and code come from the ISO 639 codes, with the two character code preferred over the three character code. These pages should also have categories [[Category:Keyboard]][[Category:Keyboard Layout]] and the category tags of countries that use this keyboard. While there may be multiple keyboards per country, multiple keyboards per language are less likely. Those could be titled "OLPC Spanish (es) Mexico Type Keyboard".
Currently, the keyboard layouts just have a category tag of Keyboard and are named after specific countries. For example, all Spanish countries, e.g., Argentina, Mexico, Chile, Argentina, etc., use the keyboard layout OLPC Argentina Keyboard because that was the first country for which the keyboard was designed. Keyboards generally go by language. The OLPC designator applies because the keyboards generally come through OLPC and it helps keep the Keyboard Category uncluttered. The ISO usage in language names and codes keeps out ambiguity.
This should changes about twenty pages including OLPC Argentina Keyboard, OLPC Armenian Keyboard, OLPC Nigeria Keyboard and others.
Comments?
  • The country tags might be overkill, given how many countries speak Spanish but have no deployments --Walter 17:21, 9 April 2008 (EDT)
    • OK. Country pages with deployments will link to the page anyway. -- Cjl 17:34, 9 April 2008 (EDT)
  • BTW, do we need a new Keyboard Template category? -- CharlesMerriam 20:45, 9 April 2008 (EDT)
    • eh, Can't hurt ---- Cjl 15:34, 10 April 2008 (EDT)


After being quiet for about a week, Cjl then makes all the changes to the articles and moves the edited proposal to the Accepted Conventions section. The comments are deleted but still available in the history page.

Active Proposals:

Accepted Conventions

Please pick a section into which you put your convention: the wiki has become rather large. When in doubt, either guess or just put under the closest major heading.

Country Pages

See description on page Category:Countries
Use Country Boxes Template on All Countries proposal
Note
It is worth investigating whether this country_box template should be reconstructed as a Semantic MediaWiki template nowthat SemWiki is available for use.

Cjl 14:41, 20 July 2008 (UTC)


Translate9.svg

Peru

 Country Information
 ISO Country Code PE
 Wikipedia Article Wikipedia Link
 Government Support Sponsored Trials
 Deployment Demonstration (under 50 machines)
 Languages
 Keyboard Layout Spanish Layout
 Written Spanish (es)
 Spoken Spanish (es)
 Secondary Written None
 Secondary Spoken English (en)


CharlesMerriam 05:44, 10 April 2008 (EDT)

Every country page will add a country box, similar to the one shown, by including the Template:Country box. This would provide a quick overview for each country, as well as make a categories detailing Government Support and Deployments. This could replace or update the outdated OLPC Status by Country(see: deployments). It solves the current problem of figuring out which keyboard goes with each country, finding the right ISO codes, and provides a reference for the languages spoken.

While this box is currently English only, a future expansion could show it in native languages with English subtitles. Also, future expansions might link to keyboards and languages better once those pages follow better standards.

This should change about 80 pages, including OLPC USA, OLPC Brazil, and OLPC Korea. I would add the country box to each page with Government Support and Deployment information as unknown. People more knowledgeable about current levels of support and deployment would need to fill those in over time. I will post a note to the talk pages of some affected pages.

Comments?

It's been a week. I'll see if I can make the changes this weekend. This will involve:

  • Making a spreadsheet with the information.
  • Filling in what is obvious, leaving a lot of information as "unknown"
  • Using Python to translate the spreadsheet into "boxes"
  • Manually placing them in each OLPC <Country> page. (Captcha mucks my script)
  • Making stub OLPC <Country> pages as necessary.

It may take about a week for everything to migrate over. CharlesMerriam 11:50, 17 April 2008 (EDT)

Sorry for not commenting earlier, but I have a question. I see how secondary langs get in, what about thrid and fourth, or more? Cjl 14:33, 17 April 2008 (EDT)

Just put them into the secondary language box. The odds they are ever localized that deep is near zero. CharlesMerriam 18:56, 30 April 2008 (EDT)

Localization

Keyboard Layouts page naming/tagging proposal

Cjl 00:39, 11 April 2008 (EDT)

  • Keyboard pages will generally be named in the form "OLPC language/script keyboard". For example, "OLPC Spanish Keyboard".
    • Language name is preferred over script (alphabet) name, especially for languages using variations of the Latin, Cyrillic or Arabic alphabets.
    • The complexities of real-world deployment challenges and clever keyboard design that allows one keyboard to be used for multiple languages can make it difficult to strictly follow the "OLPC language/script keyboard" naming convention. The OLPC Nigeria Keyboard represents an example where a single keyboard can be used to represent three languages (Igbo, Yoruba, and Hausa) for the purposes of a country-scale deployment. This is a wonderfully clever and cost-effective solution and so the solution on the wiki should try to be equally clever. The intent of the page naming guideline is to improve navigation and so accepting that the details of the deployment (Nigeria) are the more important issue, "OLPC deployment keyboard" is an acceptable alternative in conjunction with creating redirect pages from the three "OLPC language/script keyboard" pages.
    • There may be multiple keyboards per country and multiple countries using the same keyboard. However, multiple keyboards per language are less likely. If needed, extensions to the naming convention to reduce confusion and add more explicit information on deployment could be used, for example "OLPC Urdu (pk) Keyboard" for an Urdu keyboard variation specific to a Pakistan deployment.
  • Keyboard layout pages should generally have a [[Category:Keyboard]] tag.
  • Keyboard pages should generally include relevant and existing "OLPC country" category tags to improve navigation from the "OLPC country" pages. It is not useful to create "OLPC country" tags if no OLPC effort for that country is active on the wiki.

References:

ISO 3166 Codes for the representation of names of countries

ISO 15924, Codes for the representation of names of scripts

ISO 639-2 Codes for the representation of names of languages


Detailed proposal of name changes to existing keyboard page names.

Old/Current New/Proposed
OLPC Argentina Keyboard OLPC Spanish Keyboard (done)
OLPC Armenian Keyboard no change (done)
OLPC Brasil Keyboard OLPC Portuguese Keyboard (done)
OLPC Cyrillic Keyboard OLPC Russian Keyboard (done)
OLPC Dari Keyboard no change (done)
OLPC Devanagari Keyboard OLPC India Keyboard, possibly with redirects from Hindi, Marathi, etc.???
OLPC Ethiopia Keyboard OLPC Amharic Keyboard (done)
OLPC French Canadian Keyboard OLPC French (ca)(ht) Keyboard (done)
OLPC Italian Keyboard no change (done)
OLPC Kazakh Keyboard no change (done)
OLPC Khmer Keyboard no change (done)
OLPC Libya Keyboard OLPC Arabic Keyboard (done)
OLPC Mongolian Keyboard no change (done)
OLPC Nepal Keyboard OLPC Nepali Keyboard (done)
OLPC Nigeria Keyboard no change, create redirects at Igbo, Hausa, and Yoruba keyboard pages (done)
OLPC Pakistan Keyboard OLPC Urdu (pk) Keyboard
OLPC Pashto Keyboard no change (done)
OLPC Pulaar Keyboard no change (done)
OLPC Rwanda Keyboard OLPC French Keyboard (done)
OLPC Thailand Keyboard OLPC Thai Keyboard (done)
OLPC Turkey Keyboard OLPC Turkish Keyboard F-type (done)
OLPC Turkey Q-Type Keyboard May be preferred over F-type, needs to be conformed to other keyboard page styles ???
OLPC Urdu Keyboard OLPC Urdu (in ??) Keyboard
OLPC US International Keyboard OLPC English Keyboard (done)
OLPC Uzbek Keyboard no change (done)
Progress

Work is being recorded in the table above. There are still some ambiguities to be resolved that will likely require some further input from someone familiar with details of OLPC mfg process/plans, and I will continue to follow-upon these. Cjl 10:28, 3 May 2008 (EDT)

Remaining Questions
  • Is there any difference (current or planned) between OLPC Pakistan Keyboard and OLPC Urdu Keyboard?
  • Do current plans for OLPC_Devanagari_Keyboard place in a category like OLPC Nigeria where "OLPC India keyboard" is most parsimonious name with "OLPC Hindi Keyboard, OLPC Marathi Keyboard, etc." as redirects to "OLPC India Keyboard"?
Comments?
  • For Devanagari, it's the annoying exception. It is closely related to the Nepali keyboard, etc. I would suggest you name it Hindi, as you plan, and also add both to a "Devangari Keyboard" category. Nothing wrong with an extra category.
  • For the Turkish keyboards, I expect you need to keep both. Both are used in Turkey and we should wait until the XO deploys there and their Ministry of Education makes a decision. Ah, extra exceptions in case one runs out. :)
    • I'm not suggesting that the Q-type might not ever be used, it's just that the current Q-page is not in the same format as all other current keyboard pages. It looks like a stub that was edited once and abandoned in June '07, In it's current form, it should be deleted or expanded substantially to truly represent the Q-type alternative. It should be easier to review now that I've added links to the table above. Cjl 11:27, 11 April 2008 (EDT)
  • This is great, but I am a bit confused: it seems that in most cases, you are using the language name for the keyboard, which is fine, but, for example, Kreyol, why not use the name OLPC French (ca) Keyboard. It happens to be the preferred keyboard in Haiti, but it is the French Canadian keyboard. Is the rationale that we are deploying in Haiti and not in Canada? Also, why do you drop the OLPC in front of some of the Urdu keyboards? (Also, are there really two different Urdu keyboards? I suspect that the Urdu (in) keyboard is not real (yet). Nigeria does present a problem. Why not just have three different names pointing to the same layout? Same for Pashto/Dari, since the new keyboard for Afghanistan will be used for both languages. --Walter 10:29, 11 April 2008 (EDT)
    • Leaving OLPC prefix off of Urdu keyboards was simple oversight, fixed now. The chance to catch errors is one of the good things about this page. Current Pakistan and Urdu keyboard pages do indeed have identical text on their pages and I was going to propose eliminating one, but I saw what might be two differing layouts for Urdu keyboards on the Keyboard_layouts page and so I thought I would make a more conservative proposal and ask for clarification. If there is no current or intended distinction between PK and IN Urdu keyboards, then I would propose to delete OLPC Pakistan Keyboard page. Cjl 10:49, 11 April 2008 (EDT)
    • I agree with your point on Kreyol, and have changed the proposal to French (ca)(ht) Keyboard. I thought it best to put a very specific proposal up to solicit very specific improvements such as those you've provided. Cjl 11:27, 11 April 2008 (EDT)
    • For Nigeria, I added some "common-sense" exception language to the general proposal and modified the table accordingly. Like a computer program, the quality/stability of a convention or guideline is directly related to it's exception-handling ability and nothing beats remembering the intended purpose of the "rule" and using common-sense. Cjl 13:31, 11 April 2008 (EDT)


I have tried to address the very helpful comments made. Absent any genuine objections, I will begin to make these changes to the pages in the table. This will involve some page moves (for renames), and I'll try to track down links and update them as well rather than lean too heavily on redirects. Cjl 22:38, 20 April 2008 (EDT)

Retrieved from "http://wiki.laptop.org/mediawiki/index.php?title=Conventions&oldid=189794"