maria-docs team mailing list archive

[Daniel Bartholomew <dbart@xxxxxxxxxxxxxxxx>]

On Tue, 29 Nov 2011 09:23:05 +0000 (GMT)
Federico Razzoli <federico_raz@xxxxxxxx> wrote:

Federico> 
Federico> --- Lun 28/11/11, Peter Lavin <peter@xxxxxxxxxxxxx> ha
Federico> scritto:

Peter> In defence of stubs, I don't think the 'MySQL User Guide' was
Peter> very well promoted--it's hard to find, not immediately clear
Peter> that contributions are welcome

Federico> I agree. I use MySQL and its site since 2001 I 
Federico> think, and never knew of that "user guide", or suspected that 
Federico> contributes on any part of the wiki are welcome.
Federico> 
Federico> But, I think that also AskMonty KB doesn't make it
Federico> "immediatly clear":
Federico> 
Federico> * In the home page and in the sidebar, I can see no link like
Federico> "How to contribute" ("about AM KB" is not in evidence, and
Federico> it's not clear it's written for contributors)

I think a separate "How to Contribute to the KB" article is a good idea.
I'll split the how-to parts of the about page out into a separate
article (and feature it on the KB home page).

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.

The "Ask a question here" button is active for all users (logged in or
not), but now that I think about it, the "Ask a question" button only
appears on category pages and it should probably appear on all pages.

Federico> Also, MySQL docs seem to strictly follow some (good)
Federico> guidelines. AM KB doesn't: pages are written with different
Federico> styles, some categories seem to be duplicated, and many
Federico> articles are not listed in some related categories. A lack of
Federico> guidelines does not encourage people who want to contrib with
Federico> quality content.

Yes. This is one of the issues with having many contributors. When I
edit a new article contributed by someone else I generally limit myself
to correcting spelling and grammar errors. I occasionally do a more
thorough rewrite, but doing so takes time (which I may or may not have
that week).

I agree that there needs to be some category housekeeping done. This is
an ongoing thing, and will need to be done periodically as the KB grows.

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?

Thanks.

-- 
Daniel Bartholomew
MariaDB - http://mariadb.org
Monty Program - http://montyprogram.com
AskMonty Knowledgebase - http://kb.askmonty.org