maria-docs team mailing list archive

[Peter Lavin <peter@xxxxxxxxxxxxx>]

The "MySQL Documentation Style Guide" is available on this page:
http://dev.mysql.com/doc/index-other.html

It may serve as a guideline. However, it is not open source.


On 29 November 2011 13:40, Shaun McCance <shaunm@xxxxxxxxx> wrote:

> 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
>
>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~maria-docs
> Post to     : maria-docs@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~maria-docs
> More help   : https://help.launchpad.net/ListHelp
>



-- 
Peter Lavin
Telephone: 1 416 461 4991
Mobile:       1 647 985 4991
Skype:        peter.lavin