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/