[Sahana Docs] I18N in DokuWiki - proposal to change convention

[Tim McNamara]

Hi all,

Sorry to post to both lists, however this post relates to both current authors and translators.

I have been looking at the DokuWiki software that runs Sahana's wiki. They way we have languages set up makes it very hard for user navigation and does not follow the recommended protocol at http://www.dokuwiki.org/plugin:translation.

The current standard is:

namespace:page:language | doc:start:fr

I propose to migrate to:

language:namespace:page | fr:doc:start

Note that the default language, in Sahana's case - English, does not have a language identifier.

The main reason for proposing this change is that the breadcrumbs (labelled as Trace:) currently make it very difficult to know the difference between any of the pages. Seperate pages, if German were our example language, would appear as 'de' 'de' 'de', which defeats their purpose. Secondly, if we adopt the new standard - we will be able to configure the translation plugin (http://www.dokuwiki.org/plugin:translation)

which allows users to switch between languages easily.

This transition between the systems can be managed by the use of the redirect plugin.

For example, to automatically send someone from doc:start:fr to fr:doc:start, the editor would type the following into doc:start:fr:

~~REDIRECT>fr:doc:start~~

Note: if the page names are the same, e.g. if

doc:start = fr:doc:start, then the translation plugin will work fine if we choose to implement it in the future. As we currently don't use it, there is an argument for also translating the pagenames.

Any thoughts?

Tim

  http://www.timmcnamara.co.nz 

  PO Box 3125, Wellington Mail Centre 6140, New Zealand

 

[Gavin Treadgold]

One quick one ;)

On 2009-04-16, at 1417, Tim McNamara wrote:
> Note: if the page names are the same then the translation plugin

> will work fine if we choose to implement it in the future. As we
> currently don't use it, there is an argument for also translating
> the pagenames. Any thoughts?
>

I guess that the wiki should come up for discussion is the soon-to-be-
started discussion on infrastructure (I've had some feedback on a
draft that I'll incorporate in the next few hours and soon post to
kick it off).

My though is that the wiki software for documentation should also be
up for discussion - e.g. do we stick with DokuWiki or do we
investigate other wiki software? (I must admit to have always being a
fan of MediaWiki).

Whilst your great editing/updating of content can and should continue
whilst a discussion on wiki software is held, I don't know if it would
be wise to jump straight into i18n of the wiki without having a proper
discussion (as part of the infrastructure) as to where the wiki fits
in our broader infrastructure, and whether we need to change wiki
platform.

Not sure if it helps your original question, but wanted to flag that
it is part of the infra. discussion soon to start, and I'd suggest
that we carry that out further there.

Cheers Gav

[Tim McNamara]

Hi Gav-

 

Very valid points.

 

On Thu, Apr 16, 2009 at 3:35 PM, Gavin Treadgold <g...@kestrel.co.nz> wrote:

My though is that the wiki software for documentation should also be
up for discussion - e.g. do we stick with DokuWiki or do we
investigate other wiki software? (I must admit to have always being a
fan of MediaWiki).

 

I think it's important to seperate the website from the Sahana application. Changes to Sahana do not necessarily imply that the website needs to be modified - although I am sure I can remember Chamindra and others discussing the website.

Wiki software discussion

Website-wise

MediaWiki obviously has the might of Wikipedia behind it. It's familiar to everyone. It has the ability to incorporate 'discuss' pages, custom infoboxes and so forth.

However, I personally prefer DokuWiki's syntax and the fact that headings are naturally indented to demonstrate flow and structure to the reader. I also don't like how sites that use MediaWiki tend to keep the default layout, (http://wiki.HYPERLINK "http://www.open"openmoko.org is a very good exception) although the same could be said for our current implementation of DokuWiki.

Application-wise

I'm yet to determine a preference for how to include documentation as mentioned in a previous thread. I'm not sure that bundling MediaWiki will be optimal, especially if there is a move to Python. Perhaps a more lightweight option would be preferable.

My personal preferences longer term

I see three main purposes for the wiki as it currently stands. 1) Documentation, 2) Planning / Team Coordination 3) Document/Proposal review. I think each of these needs should be dealt with seperately, rather than using a monolithic approach as we currently use.

Documentation

Documentation for mature modules should move to static XHTML with downloadable PDFs for printing. In developer terminology, this would be doc-stable. This can be supplemented with doc-dev, which is a wiki namespace for immature modules and revisions. Basically, doc-dev would be what we currently have.

As far as possible, I would prefer end-users stay on http://www.sahana.org, and avoid http://wiki.sahana.org. That way, things look consistent for them and they don't perceive a change.

Planning / Team Coordination

The dev: namespace and others in the wiki should be kept pretty much as they are.

Document Review

(Note personal preferences only!)

For things such as module proposals, Launchpad's Blueprints are ideal. They're easier to input than and allow you to track comments. Every module idea can be connected to Sahana easily and everyone knows exactly the development stage, because code alterations are perfectly transparent.

For major documents, and in an ideal world, I would like to see stet (http://en.wikipedia.org/wiki/Stet_%28software%29) or co-ment (http://www.co-ment.net/) used for discussions. They will avoid duplication of effort.

Cheers,

 

Tim McNamara

  http://www.timmcnamara.co.nz 

  http://twitter.com/timClicks

[Chamindra de Silva]

On Thu, Apr 16, 2009 at 10:08 AM, Tim McNamara <mcnama...@gmail.com> wrote:

However, I personally prefer DokuWiki's syntax and the fact that headings are naturally indented to demonstrate flow and structure to the reader. I also don't like how sites that use MediaWiki tend to keep the default layout, (http://wiki.HYPERLINK "http://www.open"openmoko.org is a very good exception) although the same could be said for our current implementation of DokuWiki.

+1 for dokuwiki for the reasons above. It is also a much more development friendly WIKI compared to MediaWIKI.
 

I see three main purposes for the wiki as it currently stands. 1) Documentation, 2) Planning / Team Coordination 3) Document/Proposal review. I think each of these needs should be dealt with seperately, rather than using a monolithic approach as we currently use.

There is one more special requirement I can see and that is the integration of dokuwiki into Sahana as a online help and WIKI module. Though HTML and PDF are good output formats, we should also consider that it is useful to have an editable online help system that can be customized for the scenario, country and disaster at hand. This then can become online help not just on the system but also tailored for the country and even at a point of a disaster. Additionally it can be used as a generic WIKI for sharing information on the disaster.

I think this would be a valuable module for Sahana. PDF can also be auto generated using a Dokuwiki plugin

http://www.dokuwiki.org/plugin:pdfdownload
http://www.dokuwiki.org/plugin:pdfex

Tim, Hayesha are you interested in working to integrate this as a Sahana module?

Chamindra de Silva
http://chamindra.googlepages.com