Dedicated English website : where should we start ?

[Diederick_de_Jongh]

My main problem is the unclear structure of SPIP-resources. I experience it as a labyrinth in which I lose myself and usually I’m forced to eventually give up even though I know that, in french at least, the info I’m looking for, must be in there somewhere…

My golden rule for any successful website: Make sure the impatient user can find what he is looking for.

If the SPIP resources could somehow be harmonized and more clearly structured, as a first step, offer links to translations where available as a second step, then I’m sure the third step: more translations being offered in more languages, will come about quite quickly.

Multi-language validation by the Spip-team will become an even bigger bottle neck. Perhaps the translated docs can initially be offered anyway but without a validation stamp by the SPIP-team? At least many of us would be able to move foreward but with the understanding that translation hasn’t yet been validated.

DdJ

PS: Are there any other project websites out there that can serve as inspiration?

On Dec 3, 2007 4:46 PM, Pierre Andrews <mortimer.pa@free.fr> wrote:

Hi everyone,

I am reacting to Thomas mail as it raises problems that have been around
for a while and where things had already been experimented with.

I always wanted to get something more friendly as a frontend to SPIP,
and more easily translatable, at least to get the foot in the door as
you said. There are multiple problems with that…

A first one is that most of the French contributors, even if they do the
most to accomodate a multilingual community have other priorities (i.e.
coding features) than refactoring sites around SPIP
It’s easy to understand why, it’s already difficult to write a french
documentation, it’s even more difficult to coordinate the translators etc…
As a open source project, SPIP is on the doc writting and translation
part very open and decentralised. Everyone can log into spip.net and
write an article or a traduction about something. However, there is a
bottlenet on spip.net because there is a very small team of admins that
have to validate the articles.

Because spip.net is « official », the admins have to keep it clean and
clear and also keep it easy to translate for the translators. That’s
very difficult.

That’s a bit why the spip-contrib site and the wiki started, to take a
bit of the weight off the official administration and have a more open
approach. There are loads of discussion on the main spip-trad list (and
I think most of the question raised on this english list may be as well
discussed there so we gather more translators/documentors around the
question).

Thomas Sutton wrote:

The opportunity to contribute something back (if only a
list of documentation with new material to be translated) would be welcome.

Well, as I said earlier, spip.net is open to anyone. If someone from
bouncing orange (or you personally) want to contribute back, you are
welcome to come there or on spip-contrib. (however beware that you will
have to strip the company name out when you contribute, SPIP trying to
stay neutral there… it’s nothing against bouncing orange, you know me ;).

For the list of articles up to date and left to translate, this already
exists here:
http://www.spip.net/trad.php3
(it’s also availlable in the all site view from spip.net/ecrire )

In my personal opinion, perhaps the most useful aspect would be more
complete documentation of SPIP in English in a more flexible format –
something to give us the ability to post comments and examples (a la the
PHP manual) and a little finer grained than a single page for all of
« SPIP’s Filters ». I don’t know how the internationalisation on, e.g.,
SPIP.org is organised, but having the documentation articles split into
smaller chunks would also make it easier to translate it piecemeal and
help ensure that we non-francophones see something for every filter
(for example), even if it’s in another language. Following a link to a
page that doesn’t even mention the feature I’m looking for gets a little
annoying.

If you want, you could translate the « memento »
http://www.aozeo.com/blog/69-memento-spip-2
the sources are somewhere on spip-zone. See in the article.

I once started working on automatically splitting the current
documentation on something more flexible as you say. You can find
beginning of scripts here:

A big problem right now is that a large amount of the documentation is
written and translated in this awkward « everything on one page » style
that should be cut out in smaller parts, linked by keywords, etc… to
make a better spip.net/@ glossary.
The problem is that we cannot throw away all the translation work, this
is a big amount of text and it would be impossible to ask all the
translators to come back and split everything again. This will take a
long time and we need to find a transition method to get from where we
are now to where we want to go.

I actually have no time to coordinate that, so it stayed a bit behind
for now, but anyone could take the job

A second feature of such a web site that I would love would be a
collection of articles describing best practice, SPIP’s insides, etc.
After two months of working with SPIP, I still have the feeling that I’m
missing things that would make my work a lot ‹ cleaner, › if not easier
and quicker.

That can be started when you want, either from the spip.net site (if
admins there are happy with that, personally, I’ll be happy to see
something like that), doc.spip.org or spip-contrib, it’s wiki… or even
as articles for the mag.
There is a will to keep spip.net as clean and newbee friendly as
possible, with the minimum of geekyness… but that’s probably unavoidable.
Articles don’t have to be written in French then translated. Anyone can
write in their language and then try to translate back to as many other
languages as possible…

Now, to react on the initial idea of having a English oriented site. I
think this is a bit strange and, as many participants have already
voiced, just reflect a general language neutral need to have a better
portal to access information around SPIP.

Pierre

---

spip-en@rezo.net - http://listes.rezo.net/mailman/listinfo/spip-en

[Mortimer_Porte (Pierre Andrews)]

Diederick de Jongh wrote:

Multi-language validation by the Spip-team will become an even bigger bottle neck. Perhaps the translated docs can initially be offered anyway but without a validation stamp by the SPIP-team? At least many of us would be able to move foreward but with the understanding that translation hasn't yet been validated.

Well, the bottleneck I was talking about is for the main documentation in French, not the translations, usually, these are validated quite quickly by another admin of the language.

Articles on spip-contrib are usually published faster for example when they are not essential documentations, tips, etc...

Pierre

[Thomas_Sutton]

Hi folks,

(Again, this message was written out of order, so please excuse any repetition.)

On 04/12/2007, at 12:46 AM, Pierre Andrews wrote:

Hi everyone,

A first one is that most of the French contributors, even if they do the
most to accomodate a multilingual community have other priorities (i.e.
coding features) than refactoring sites around SPIP
It's easy to understand why, it's already difficult to write a french
documentation, it's even more difficult to coordinate the translators etc...
As a open source project, SPIP is on the doc writting and translation
part very open and decentralised. Everyone can log into spip.net and
write an article or a traduction about something. However, there is a
bottlenet on spip.net because there is a very small team of admins that
have to validate the articles.

Because spip.net is "official", the admins have to keep it clean and
clear and also keep it easy to translate for the translators. That's
very difficult.

That's a bit why the spip-contrib site and the wiki started, to take a
bit of the weight off the official administration and have a more open
approach. There are loads of discussion on the main spip-trad list (and
I think most of the question raised on this english list may be as well
discussed there so we gather more translators/documentors around the
question).

This is entirely understandable, but I think that the affect that it has might make it worth while to change. First, the current format has an easily observable negative effect on the maintaining the documentation (see below) and the 'whole document' approach raises the barrier to entry for translators and editors. Smaller units of text would make it easier and quicker for people to make changes -- I'll probably spend a couple of hours going over one or two English SPIP.net pages tonight, if it was quicker and easier, I'd be doing them now instead of just talking about it Second, a more granular approach would make it easier to ensure that translation and editing tracks the reference documents much more quickly than is currently the case -- who wants to update "SPIP's Filters" when they'll have to trawl through it looking for the changes? Much easier to update "SPIP's Filters -> The plus filter".

Thomas Sutton wrote:

The opportunity to contribute something back (if only a
list of documentation with new material to be translated) would be welcome.

Well, as I said earlier, spip.net is open to anyone. If someone from
bouncing orange (or you personally) want to contribute back, you are
welcome to come there or on spip-contrib. (however beware that you will
have to strip the company name out when you contribute, SPIP trying to
stay neutral there... it's nothing against bouncing orange, you know me ;).

For the list of articles up to date and left to translate, this already
exists here:
Bilan des traductions
(it's also availlable in the all site view from spip.net/ecrire)

Being only monolingual I'll leave the translation to others (or, perhaps, work with my multilingual colleagues) and focus on fixing incomplete and bit-rotted documentation. I've just this morning got my SPIP.net password e-mail, so you can expect to see a raft of changes to the English version of "SPIP's Filters" some time in the next day or so (I count 19 filters described in the French version but omitted or in need of updating in the English, many of which I'd like to have known about).

In my personal opinion, perhaps the most useful aspect would be more
complete documentation of SPIP in English in a more flexible format --
something to give us the ability to post comments and examples (a la the
PHP manual) and a little finer grained than a single page for all of
"SPIP's Filters". I don't know how the internationalisation on, e.g.,
SPIP.org is organised, but having the documentation articles split into
smaller chunks would also make it easier to translate it piecemeal and
help ensure that we non-francophones see *something* for every filter
(for example), even if it's in another language. Following a link to a
page that doesn't even mention the feature I'm looking for gets a little
annoying.

If you want, you could translate the "memento"
http://www.aozeo.com/blog/69-memento-spip-2
the sources are somewhere on spip-zone. See in the article.

I once started working on automatically splitting the current
documentation on something more flexible as you say. You can find
beginning of scripts here:

A big problem right now is that a large amount of the documentation is
written and translated in this awkward "everything on one page" style
that should be cut out in smaller parts, linked by keywords, etc... to
make a better spip.net/@ glossary.
The problem is that we cannot throw away all the translation work, this
is a big amount of text and it would be impossible to ask all the
translators to come back and split everything again. This will take a
long time and we need to find a transition method to get from where we
are now to where we want to go.

I actually have no time to coordinate that, so it stayed a bit behind
for now, but anyone could take the job

I'll have a look at it (I haven't looked at SPIP's support for multilingual sites yet) and might volunteer to develop a prototype if I have time. Being unable to use the French documentation, I encounter the problems with the current approach more than some might and I think that this "all or nothing" approach is probably a/the main cause.

A second feature of such a web site that I would *love* would be a
collection of articles describing best practice, SPIP's insides, etc.
After two months of working with SPIP, I still have the feeling that I'm
missing things that would make my work a lot 'cleaner,' if not easier
and quicker.

That can be started when you want, either from the spip.net site (if
admins there are happy with that, personally, I'll be happy to see
something like that), doc.spip.org or spip-contrib, it's wiki... or even
as articles for the mag.
There is a will to keep spip.net as clean and newbee friendly as
possible, with the minimum of geekyness... but that's probably unavoidable.
Articles don't have to be written in French then translated. Anyone can
write in their language and then try to translate back to as many other
languages as possible...

I find this goal of newbie friendliness admirable, but the downside is that when I want or need to know more, I have to use grep to figure it out myself or fall back on this list. I'm at the stage now where I'm reasonably comfortable "getting it to work" and I'd like to move on to "getting it to work well"

Now, to react on the initial idea of having a English oriented site. I
think this is a bit strange and, as many participants have already
voiced, just reflect a general language neutral need to have a better
portal to access information around SPIP.

For what it's worth, I agree with this point of view -- I don't see the need for any language specific sites or communities. Indeed I think it would probably encourage a degree of fragmentation that isn't helpful or healthy for the community. Instead I'd prefer to see some guidelines on how and where I and other anglo- and other-phones can contribute more readily and (perhaps as a result of our following those guidelines) more information on going further after we've successfully got started.

Perhaps a guided tour of the SPIP-o-sphere would be a good start?

Cheers,

Thomas
(Who is excited to have the opportunity to contribute)

P.S.: We've encountered a few edge cases where SPIP probably should detect error conditions and doesn't. What's the correct way to lodge bug reports and feature requests? Is there an issue tracker for SPIP?

[epilibre (Gilles Vincent)]

On 12/4/07, Thomas Sutton <thomas@bouncingorange.com> wrote:

I'll probably spend a couple of hours going over one or two English
SPIP.net pages tonight, if it was quicker and easier, I'd be doing
them now instead of just talking about it Second, a more granular
approach would make it easier to ensure that translation and editing
tracks the reference documents much more quickly than is currently
the case -- who wants to update "SPIP's Filters" when they'll have to
trawl through it looking for the changes? Much easier to update
"SPIP's Filters -> The plus filter".

> Thomas Sutton wrote:
>> The opportunity to contribute something back (if only a
>> list of documentation with new material to be translated) would be
>> welcome.
>

The documentation also is far from beeing complete, even for the
french version.
When you look at all the filters availables in ecrire/inc/filtres.php,
you can find lots of them which are not documented :

ex.
#SET{test,#ARRAY{1,'val1',2,'val2'}}
[(#GET{test}|table_valeur{1})]

I've done a list here :
http://article.gmane.org/gmane.comp.web.spip.devel/44517
and here :
http://article.gmane.org/gmane.comp.web.spip.devel/44518

That's right that some of them are really technicals and may be
usefull only for plugin developpers. However I personnaly think that
such filters (even if some of them are only in the svn version) should
be documented somewhere.

Of course you can find documentation on http://doc.spip.org
(ex. http://doc.spip.org/@table_valeur)
But it's only in french, and contributing here is really difficult.

.Gilles

[Mortimer_Porte (Pierre Andrews)]

Thomas Sutton wrote:

I'll have a look at it (I haven't looked at SPIP's support for multilingual sites yet) and might volunteer to develop a prototype if I have time. Being unable to use the French documentation, I encounter the problems with the current approach more than some might and I think that this "all or nothing" approach is probably a/the main cause.

ok, I realize I didn't send the link to the scripts I mentioned:
http://trac.spip.org/trac/spip-zone/browser/_acotes_/cheatsheet
They are a year old, but a good start. You can use them to extract all filters, loops, etc... from the php files.

A prototype would be cool I think. If you wanna start from the existing spip.net templates, they are also on spip-zone, and you can ask spip-zone@rezo.net for a SVN access if you want to start a new template project for that.

I know it's a great problem and would really like to get it done... but right now, I have too many other thing to do that I can't (I shouldn't be posting here neither)

I find this goal of newbie friendliness admirable, but the downside is that when I want or need to know more, I have to use grep to figure it out myself or fall back on this list. I'm at the stage now where I'm reasonably comfortable "getting it to work" and I'd like to move on to "getting it to work well"

I know, I know... but some technical articles could as well be published on spip-contrib, doc.spip.org (the technical documentation) or as editorial articles on the mag. If these site are referenced properly around the spip "galaxy", then they would still be available for advanced users but wouldn't scare "normal" people
It probably doesn't show on this list as most of the English speaking crowd using SPIP is a motivated, technical crowd, but SPIP is used by loads of newbies (you can see that in the forums and the French mailing list) and this is the way the dev have always wanted it I suppose.

Now, to react on the initial idea of having a English oriented site. I
think this is a bit strange and, as many participants have already
voiced, just reflect a general language neutral need to have a better
portal to access information around SPIP.

For what it's worth, I agree with this point of view -- I don't see the need for any language specific sites or communities. Indeed I think it would probably encourage a degree of fragmentation that isn't helpful or healthy for the community. Instead I'd prefer to see some guidelines on how and where I and other anglo- and other-phones can contribute more readily and (perhaps as a result of our following those guidelines) more information on going further after we've successfully got started.

It's not clear and a bit scary, but anyone can contribute:
- articles on spip.net, modulo the quality factor I already mentioned
- write contributions on spip-contrib, in their own language. These are usually published quickly adn without as much restrictions as in spip.net
- use the wiki: Carnet Wiki even if this is not really made as a multilingual space (no translation links, etc... yet, but it's all backed up by SPIP, so the multilingual feature are there), there were sections for other languages (I can't find them anymore...)

Perhaps a guided tour of the SPIP-o-sphere would be a good start?

this would be interesting, but I think noone really understands how it work. It's always hard to decide where what goes... But google likes spip and it's usually very fast at finding what you want

Pierre

[Mortimer_Porte (Pierre Andrews)]

Thomas Sutton wrote:

Being only monolingual I'll leave the translation to others (or, perhaps, work with my multilingual colleagues) and focus on fixing incomplete and bit-rotted documentation. I've just this morning got my SPIP.net password e-mail, so you can expect to see a raft of changes to the English version of "SPIP's Filters" some time in the next day or so (I count 19 filters described in the French version but omitted or in need of updating in the English, many of which I'd like to have known about).

Ok, gogogo

there are a few guidelines to continue on how things are written right now:
1- historical changes should be kept in the doc. So no erasing of something that's now changed, you will have to put something like "in SPIP 1.8, this was working like... in SPIP 1.9, the filter XXX does..." (that's another bad part of the doc I think)
2- because of how SPIP manages rights, you won't have the right to directly edit the filter article. Either write a new one, or write in the comments and notify the spip-trad@rezo.net list so that an admin can transfer the corrections (the bottleneck I was talking about
3- when you write new things, try to keep it clear for the largest number of users and use language that can but understood by the translators, avoiding colloquialism, etc..

I am sorry if it's that complicated

Pierre

[Paolo]

Pierre Andrews wrote:

2- because of how SPIP manages rights, you won't have the right to directly edit the filter article. Either write a new one, or write in the comments and notify the spip-trad list

Hi, seeing that this discussion was starting up (and realising that there is at least one person in the world who tries to use the English documentation!) I asked Fil yesterday if we could have the autorité plugin installed on spip.net. This could make it possible for authors who are not admins to update articles directly, and would make for a more flexible approach to translating. He seemed to think it would be a good idea to install the plugin. When it may be ready though, I do not know.

Paolo

[Mortimer_Porte (Pierre Andrews)]

Paolo wrote:

Pierre Andrews wrote:

2- because of how SPIP manages rights, you won't have the right to directly edit the filter article. Either write a new one, or write in the comments and notify the spip-trad list

Hi, seeing that this discussion was starting up (and realising that there is at least one person in the world who tries to use the English documentation!) I asked Fil yesterday if we could have the autorité plugin installed on spip.net. This could make it possible for authors who are not admins to update articles directly, and would make for a more flexible approach to translating. He seemed to think it would be a good idea to install the plugin. When it may be ready though, I do not know.

Ho that would be sooooo cool. It a bit depressing when you scare translators and documentors with this validation system

Pierre

[Paolo]

Thomas Sutton wrote (on 4 December):

I've just this morning got my SPIP.net password e-mail, so you can expect to see a raft of changes to the English version of "SPIP's Filters" some time in the next day or so (I count 19 filters described in the French version but omitted or in need of updating in the English, many of which I'd like to have known about).

Thomas,

I saw you made a start on a new article "SPIP's filters" on 4 December.

As you pointed out, the problem with the existing article is that it is not up-to-date.

We now have the plugin "autorité" installed on spip.net. This (as presently configured) should make it possible for all the authors of an article to update their articles.

I have added you as an author to the original "SPIP's Filters" article
http://www.spip.net/ecrire/?exec=articles&id_article=2465

Can you take a look and see if you, with the help of your French-speaking colleague(s) can try to get it up-to-date in English? It certainly is one of the key reference articles for those working on SPIP templates.

(Who is excited to have the opportunity to contribute)

Sorry it has taken so long to get this organised, and I hope your excitement is still present!

Paolo

[Paolo]

Mark Baber wrote (last month!):

I've made a handful of translations myself,

Mark, I am very sorry: I only realised this evening that you did a couple of translations in December which have been waiting "submitted" since then. They are now published.

Wouldn't it be better to work on integrating better, and unifying our
efforts,

I don't know that it is up to me to do any integrating, but it is sure that if all those on this list who have expressed an interest do something then progress will be quickly visible!

I think that the real urgency on the English pages of spip.net is to update the technical refence pages which have lagged far behind the French.

We now have the plugin "autorité" which makes it possible for the authors to update their own articles. Do you see any existing articles which are out-of-date in English and which you could complete/update? If so, let me know and I can add you as an author so that you can edit them.

best wishes,
Paolo