maria-docs team mailing list archive

[Colin Charles <colin@xxxxxxxxxxxxxxxx>]

Hi!

On 30 Nov 2011, at 02:40, Shaun McCance 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.
> 

I agree. Simply telling people who land that their contributions are welcome, makes a lot of sense

>> 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.

This styleguide is what I consider contributes to a lot of woe for potential contributors. Sun had a docs team, and they created a very cogent style guide, but for the average joe, the learning curve was very high.

I say this as not just someone speaking ill of styleguides, but the fact that I too have in the past contributed to GNOME release notes[1][2] (significantly easier than docs, eh? :P). I recall styleguides, XML, source code revision, and a lot of added woe. Wikipedia (and the KB) is in comparison simple & easy to edit. Our current release notes are much easier to write (the changelogs on the other hand, I tip my hat off to Daniel, because I did it once for a large version when he was on vacation and all I can say is I totally respect the work he does -- its no easy task)

> 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.

Definitely. I wonder how many people it turned off though? ;-)

> 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.

I think mentoring is something we could be doing better

I for one always look at another article in the KB to check style. I forget when to use the macros, so I totally rely on previous documentation. I know its not a style guide, but its comparatively "easier" for me I guess. But its a barrier to entry

If we're focusing on increasing documentation contributors and having a really good manual that tops out even the MySQL manual, we have to make it dead easy methinks

	cheers,
	-c

[1] - http://library.gnome.org/misc/release-notes/2.6/
[2] - http://library.gnome.org/misc/release-notes/2.8/
--
Colin Charles, http://bytebot.net/blog/ | twitter: @bytebot | skype: colincharles
MariaDB: Community developed. Feature enhanced. Backward compatible.
Download it at: http://www.mariadb.org/
Open MariaDB/MySQL documentation at the Knowledgebase: http://kb.askmonty.org/