maria-docs team mailing list archive

[Shaun McCance <shaunm@xxxxxxxxx>]

On Tue, 2011-11-29 at 10:20 -0500, Daniel Bartholomew wrote:
> On Tue, 29 Nov 2011 09:23:05 +0000 (GMT)
> Federico> * Categories don't have an "add page" link, nor articles have
> Federico> "edit" button visible to anyone (they could be disabled for
> Federico> non-registered users)
> 
> Yes, they are disabled for non-logged-in users. We made the decision a
> while back that we didn't want to allow completely anonymous editing.

Probably for the best. But a link like "log in or sign up to edit"
lets people know that they can contribute if they get an account.
A very prominent "Contribute" link can do the same, though.

> Federico> I think that this is a problem for translations, too. I'm
> Federico> trying to write quality translations into italian, but I'm
> Federico> following my own style. What will happen when more italian
> Federico> users will add their own contributes? All italian translation
> Federico> projects I know have public guidelines, and lack of
> Federico> rules/help may lead to bad translations, in my opinion.
> 
> We could create a style guide for the KB, or even a brief list of
> guidelines, or "documentation best practices". Does anyone know how
> useful such things have been in other projects?

I can give some input there. In GNOME, we have a decade-old style
guide from when Sun managed our docs and we wrote book-like manuals.
It has almost nothing to do with our current writing style and best
practices. We've started on a new style guide, but it hasn't been
published yet.

Because the old style guide is still on the web, and it's still the
top hit for search phrases like "GNOME style guide", people find it
and follow it. We regularly get people following some outdated bit
of advice. So that at least indicates that some people do look for
a style guide when contributing.

We also mentor new contributors. We walk them through writing new
pages, review those pages, and make suggestions. We'll often point
to existing pages as examples of our preferred style. That serves
as a sort of bad substitute for a style guide, but it's hard to
scale, and it only works if there's a core community that already
has a common style.

--
Shaun