Hi all, What are your thoughts on adding stub articles/sections to the KB? For example, adding an article for how to specify account names without actually writing the content, along with a note to whoever comes along about what the article should contain. I've seen stubs work well in other docs efforts. They're an easy way for contributors to cherry pick work. But with the "everything is always published" model of a wiki-like KB, stubs can be annoying to average readers, like a 90s-esque "under construction" banner. Thoughts? -- Shaun
Hi, I used to subscribe to the view that stubs are "an easy way for contributors to cherry pick work". About four years ago as a MySQL employee I was involved in setting up and contributing to the 'MySQL User Guide' at http://forge.mysql.com/wiki/MySQL_User_Guide. I just did a quick review of that wiki and don't see a single element added to the original content. Not terribly encouraging. In defence of stubs, I don't think the 'MySQL User Guide' was very well promoted--it's hard to find, not immediately clear that contributions are welcome and perhaps the size of the project is overly ambitious. On 28 November 2011 16:14, Shaun McCance <shaunm@gnome.org> wrote:
Hi all,
What are your thoughts on adding stub articles/sections to the KB? For example, adding an article for how to specify account names without actually writing the content, along with a note to whoever comes along about what the article should contain.
I've seen stubs work well in other docs efforts. They're an easy way for contributors to cherry pick work. But with the "everything is always published" model of a wiki-like KB, stubs can be annoying to average readers, like a 90s-esque "under construction" banner.
Thoughts?
-- Shaun
_______________________________________________ Mailing list: https://launchpad.net/~maria-docs Post to : maria-docs@lists.launchpad.net 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
On Mon, 2011-11-28 at 17:09 -0500, Peter Lavin wrote:
Hi,
I used to subscribe to the view that stubs are "an easy way for contributors to cherry pick work".
About four years ago as a MySQL employee I was involved in setting up and contributing to the 'MySQL User Guide' at http://forge.mysql.com/wiki/MySQL_User_Guide. I just did a quick review of that wiki and don't see a single element added to the original content. Not terribly encouraging.
Sorry, I didn't mean that to imply that I think stubs alone will bring in contributors. They won't. They're just one way (of many) to provide a TODO list for contributors you're otherwise bringing in. That said, a page like this isn't at all encouraging: http://forge.mysql.com/wiki/MySQL_User_Guide_Part_V_Using_the_MySQL_APIs There's a serious risk of having too much outline and not enough real content. I wouldn't even know where to begin on that page. There's no complete sections to use as a model. There's no notes to contributors about what's expected in each section. (Yes, I intentionally picked the most egregious page. Other pages are better.) So, yeah, stubs take work to make them less off-putting, especially in always-published content. -- Shaun
--- Lun 28/11/11, Peter Lavin <peter@softcoded.com> ha scritto: In defence of stubs, I don't think the 'MySQL User Guide' was very well promoted--it's hard to find, not immediately clear that contributions are welcome I agree. I use MySQL and its site since 2001 I think, and never knew of that "user guide", or suspected that contributes on any part of the wiki are welcome. But, I think that also AskMonty KB doesn't make it "immediatly clear": * In the home page and in the sidebar, I can see no link like "How to contribute" ("about AM KB" is not in evidence, and it's not clear it's written for contributors) * Categories don't have an "add page" link, nor articles have "edit" button visible to anyone (they could be disabled for non-registered users) Also, MySQL docs seem to strictly follow some (good) guidelines. AM KB doesn't: pages are written with different styles, some categories seem to be duplicated, and many articles are not listed in some related categories. A lack of guidelines does not encourage people who want to contrib with quality content. I think that this is a problem for translations, too. I'm trying to write quality translations into italian, but I'm following my own style. What will happen when more italian users will add their own contributes? All italian translation projects I know have public guidelines, and lack of rules/help may lead to bad translations, in my opinion. Cheers Federico
On Tue, 29 Nov 2011 09:23:05 +0000 (GMT) Federico Razzoli <federico_raz@yahoo.it> wrote: Federico> Federico> --- Lun 28/11/11, Peter Lavin <peter@softcoded.com> 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
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
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@gnome.org> 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@lists.launchpad.net 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
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/
Hi! On 29 Nov 2011, at 17:23, Federico Razzoli wrote:
Also, MySQL docs seem to strictly follow some (good) guidelines. AM KB doesn't: pages are written with different styles, some categories seem to be duplicated, and many articles are not listed in some related categories. A lack of guidelines does not encourage people who want to contrib with quality content.
MySQL docs officially are written by a docs team, which at any one time has about four or so employees on staff I think. The Knowledgebase at the moment seems to be more free-form, which I guess is a lot more problematic when you want to distribute quality content and translate it all in a similar way It might make sense to have a "style guide", but the more complex it gets, the more it turns off contributors (IMHO) -- 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/
On Mon, 28 Nov 2011 16:14:34 -0500 Shaun McCance <shaunm@gnome.org> wrote: Shaun> Hi all, Shaun> Shaun> What are your thoughts on adding stub articles/sections to the Shaun> KB? For example, adding an article for how to specify account Shaun> names without actually writing the content, along with a note to Shaun> whoever comes along about what the article should contain. Shaun> Shaun> I've seen stubs work well in other docs efforts. They're an easy Shaun> way for contributors to cherry pick work. But with the Shaun> "everything is always published" model of a wiki-like KB, stubs Shaun> can be annoying to average readers, like a 90s-esque "under Shaun> construction" banner. Shaun> Shaun> Thoughts? I'm fine with the idea of stubs, as long as they don't get lost or forgotten about. They are a good way to encourage participation and plot a course for what to add to the KB next. To keep track of them, we could add a checkbox to the edit page to mark whether or not a page is considered a stub, and then have a special page that lists all stubs. Bryan: what you you think? Thanks. -- Daniel Bartholomew MariaDB - http://mariadb.org Monty Program - http://montyprogram.com AskMonty Knowledgebase - http://kb.askmonty.org
On Tue, 2011-11-29 at 09:54 -0500, Daniel Bartholomew wrote:
On Mon, 28 Nov 2011 16:14:34 -0500 Shaun McCance <shaunm@gnome.org> wrote:
Shaun> Hi all, Shaun> Shaun> What are your thoughts on adding stub articles/sections to the Shaun> KB? For example, adding an article for how to specify account Shaun> names without actually writing the content, along with a note to Shaun> whoever comes along about what the article should contain. Shaun> Shaun> I've seen stubs work well in other docs efforts. They're an easy Shaun> way for contributors to cherry pick work. But with the Shaun> "everything is always published" model of a wiki-like KB, stubs Shaun> can be annoying to average readers, like a 90s-esque "under Shaun> construction" banner. Shaun> Shaun> Thoughts?
I'm fine with the idea of stubs, as long as they don't get lost or forgotten about. They are a good way to encourage participation and plot a course for what to add to the KB next.
To keep track of them, we could add a checkbox to the edit page to mark whether or not a page is considered a stub, and then have a special page that lists all stubs.
Instead of a boolean flag for stubs, how about an enum field for status? Stubs would be one status. This could help you keep track of which pages you've thoroughly reviewed, for example. -- Shaun
On Wed, 2011-11-30 at 13:32 -0500, Shaun McCance wrote:
On Tue, 2011-11-29 at 09:54 -0500, Daniel Bartholomew wrote:
I'm fine with the idea of stubs, as long as they don't get lost or forgotten about. They are a good way to encourage participation and plot a course for what to add to the KB next.
To keep track of them, we could add a checkbox to the edit page to mark whether or not a page is considered a stub, and then have a special page that lists all stubs.
Instead of a boolean flag for stubs, how about an enum field for status? Stubs would be one status. This could help you keep track of which pages you've thoroughly reviewed, for example.
(Just throwing ideas in the ring. Take them or leave them.) Another option would be to have a stub macro, like this: <<stub>> This article is a stub. [[contribute|Help us write it.]] <</stub>> I don't know the internals of the KB. If it parses pages when they're saved, it could store a stub count per-page, and generate a report of all pages with a stub count > 0. Pros: * It encourages people to write a blurb telling users the page is a stub, and what they can do to help. * It can be used to stub sections in a page, which I think is useful sometimes. Just do this: == SSL Options <<stub>> This section is a stub. [[contribute|Help us write it.]] <</stub>> This would be picked up by a save-time stub counter as well. -- Shaun
Hi all, On 11/30/2011 12:32 PM, Shaun McCance wrote:
On Tue, 2011-11-29 at 09:54 -0500, Daniel Bartholomew wrote:
On Mon, 28 Nov 2011 16:14:34 -0500 Shaun McCance<shaunm@gnome.org> wrote:
Shaun> Hi all, Shaun> Shaun> What are your thoughts on adding stub articles/sections to the Shaun> KB? For example, adding an article for how to specify account Shaun> names without actually writing the content, along with a note to Shaun> whoever comes along about what the article should contain. Shaun> Shaun> I've seen stubs work well in other docs efforts. They're an easy Shaun> way for contributors to cherry pick work. But with the Shaun> "everything is always published" model of a wiki-like KB, stubs Shaun> can be annoying to average readers, like a 90s-esque "under Shaun> construction" banner. Shaun> Shaun> Thoughts?
I'm fine with the idea of stubs, as long as they don't get lost or forgotten about. They are a good way to encourage participation and plot a course for what to add to the KB next.
I like the thought of stubs helping people to participate but as many others have said, I'm very worried about it a) cluttering up the KB and b) not actually helping. A first step could just be a "Requested Articles" page, and add a link to a "Want to contribute?" in the sidebar and at the bottom of article listings.
To keep track of them, we could add a checkbox to the edit page to mark whether or not a page is considered a stub, and then have a special page that lists all stubs.
Instead of a boolean flag for stubs, how about an enum field for status? Stubs would be one status. This could help you keep track of which pages you've thoroughly reviewed, for example.
If we do add stubs, nstead of adding another option to the status field or a dedicated check box, I propose going forward with adding tags to the KB. The multiple parents was seen by some as a replacement for tags, but I think they can complement each other and as an alternative way to find what you are looking for. Thoughts? P.S. I'm now back in town so I actually will be able to participate in this discussion instead of only reading from my phone. -- Bryan Alsdorf, Lead Web Developer Monty Program AB. http://montyprogram.com
On Mon, 05 Dec 2011 16:44:05 -0600 Bryan Alsdorf <bryan@askmonty.org> wrote: Bryan> Hi all, Hello! Forgot to reply to this. Bryan> On 11/30/2011 12:32 PM, Shaun McCance wrote: Shaun> On Tue, 2011-11-29 at 09:54 -0500, Daniel Bartholomew wrote: Daniel> On Mon, 28 Nov 2011 16:14:34 -0500 Daniel> Shaun McCance<shaunm@gnome.org> wrote: Shaun> Hi all, Shaun> Shaun> What are your thoughts on adding stub Shaun> articles/sections to the KB? For example, adding an Shaun> article for how to specify account names without Shaun> actually writing the content, along with a note to Shaun> whoever comes along about what the article should Shaun> contain. Shaun> Shaun> I've seen stubs work well in other docs efforts. Shaun> They're an easy way for contributors to cherry pick Shaun> work. But with the "everything is always published" Shaun> model of a wiki-like KB, stubs can be annoying to Shaun> average readers, like a 90s-esque "under construction" Shaun> banner. Shaun> Shaun> Thoughts? Daniel> I'm fine with the idea of stubs, as long as they don't get Daniel> lost or forgotten about. They are a good way to encourage Daniel> participation and plot a course for what to add to the KB Daniel> next. Bryan> I like the thought of stubs helping people to participate but as Bryan> many others have said, I'm very worried about it a) cluttering Bryan> up the KB and b) not actually helping. Bryan> Bryan> A first step could just be a "Requested Articles" page, and add Bryan> a link to a "Want to contribute?" in the sidebar and at the Bryan> bottom of article listings. I think the list of tasks on http://kb.askmonty.org/en/contributing-to-the-askmonty-knowledgebase#tasks ...is a good start for a "Requested Articles" page. I'm fine with a dedicated page if others like the idea. Peppering "Want to contribute?" links around the site is a good idea and they should link to the above "Contributing to the AskMonty Knowledgebase" article. Daniel> To keep track of them, we could add a checkbox to the edit Daniel> page to mark whether or not a page is considered a stub, and Daniel> then have a special page that lists all stubs. Shaun> Instead of a boolean flag for stubs, how about an enum field Shaun> for status? Stubs would be one status. This could help you Shaun> keep track of which pages you've thoroughly reviewed, for Shaun> example. Bryan> If we do add stubs, nstead of adding another option to the Bryan> status field or a dedicated check box, I propose going forward Bryan> with adding tags to the KB. The multiple parents was seen by Bryan> some as a replacement for tags, but I think they can complement Bryan> each other and as an alternative way to find what you are Bryan> looking for. Bryan> Bryan> Thoughts? I know we've talked about tagging articles as being relevant for specific releases, so am I correct in thinking in that instance the tag would be something like "MariaDB 5.2.10" for something that only applies to MariaDB 5.2.10 or "MariaDB 5.2" (if it applies to any 5.2 release)? (just trying to make sure I'm remembering our previous discussions correctly) For things like stub articles, would we just adopt a convention of adding a "stub" tag to articles which are stubs? I guess I'm just wondering about the mechanics of how the tags would work in practice. For example, would there be a pre-defined list that people can choose from or will the tags be more free-form? Free form would be much easier, I'm guessing, from an admin point of view, but we would need to agree on a set of conventions (and maybe write them down somewhere) so we don't end up with lots of very similar-but-not-quite-the-same tags. And we should probably have a "tag review" tool that easily lets us combine similar tags together. Bryan> P.S. I'm now back in town so I actually will be able to Bryan> participate in this discussion instead of only reading from my Bryan> phone. Welcome back! I hope your vacation was fun! -- Daniel Bartholomew MariaDB - http://mariadb.org Monty Program - http://montyprogram.com AskMonty Knowledgebase - http://kb.askmonty.org
Hi Daniel, On 12/07/2011 02:30 PM, Daniel Bartholomew wrote:
Bryan> I like the thought of stubs helping people to participate but as Bryan> many others have said, I'm very worried about it a) cluttering Bryan> up the KB and b) not actually helping. Bryan> Bryan> A first step could just be a "Requested Articles" page, and add Bryan> a link to a "Want to contribute?" in the sidebar and at the Bryan> bottom of article listings.
I think the list of tasks on http://kb.askmonty.org/en/contributing-to-the-askmonty-knowledgebase#tasks ...is a good start for a "Requested Articles" page. I'm fine with a dedicated page if others like the idea.
Peppering "Want to contribute?" links around the site is a good idea and they should link to the above "Contributing to the AskMonty Knowledgebase" article.
Any other places for the link other then in the sidebar and at the bottom of the article list?
Daniel> To keep track of them, we could add a checkbox to the edit Daniel> page to mark whether or not a page is considered a stub, and Daniel> then have a special page that lists all stubs.
Shaun> Instead of a boolean flag for stubs, how about an enum field Shaun> for status? Stubs would be one status. This could help you Shaun> keep track of which pages you've thoroughly reviewed, for Shaun> example.
Bryan> If we do add stubs, instead of adding another option to the Bryan> status field or a dedicated check box, I propose going forward Bryan> with adding tags to the KB. The multiple parents was seen by Bryan> some as a replacement for tags, but I think they can complement Bryan> each other and as an alternative way to find what you are Bryan> looking for. Bryan> Bryan> Thoughts?
I know we've talked about tagging articles as being relevant for specific releases, so am I correct in thinking in that instance the tag would be something like "MariaDB 5.2.10" for something that only applies to MariaDB 5.2.10 or "MariaDB 5.2" (if it applies to any 5.2 release)? (just trying to make sure I'm remembering our previous discussions correctly)
The product / version tagging would be something different. It needs to be a lot more structured as it would actually tag certain sections of text, not just an article.
For things like stub articles, would we just adopt a convention of adding a "stub" tag to articles which are stubs? I guess I'm just wondering about the mechanics of how the tags would work in practice.
For example, would there be a pre-defined list that people can choose from or will the tags be more free-form? Free form would be much easier, I'm guessing, from an admin point of view, but we would need to agree on a set of conventions (and maybe write them down somewhere) so we don't end up with lots of very similar-but-not-quite-the-same tags. And we should probably have a "tag review" tool that easily lets us combine similar tags together.
These are questions that need to be hashed out. a pre-defined list is simple and cleaner but less flexible. I would probably start off with this and if needed allow free-form tags to be added. I am interested in what others think of this idea. Best Regards, -- Bryan Alsdorf, Lead Web Developer Monty Program AB. http://montyprogram.com
Hi! On 29 Nov 2011, at 05:14, Shaun McCance wrote:
Hi all,
What are your thoughts on adding stub articles/sections to the KB? For example, adding an article for how to specify account names without actually writing the content, along with a note to whoever comes along about what the article should contain.
I think stub articles are great, but I also think we have some problems with stubs that say, Wikipedia won't have: 1. will we create and forget about stubs (I have in the past -- now we have Pending articles) 2. who moderates once stubs get created? Wikipedia has a very active community of editors. Removing spam is comparatively easy, ensuring quality is a whole other thing (I know now Daniel does a lot of this) 3. how do we drive people to create articles that are in stubs? Question #3 interests me greatly. Wikipedia is free of ads, and you see Jimmy Wales beg you at the end of every year. The KB has ads (which I prefer, to begging, fwiw) Wikipedia is free-form knowledge. The KB is focused on SQL, MySQL, MariaDB (what I would consider more niche - i.e. barrier to entry is higher)
I've seen stubs work well in other docs efforts. They're an easy way for contributors to cherry pick work. But with the "everything is always published" model of a wiki-like KB, stubs can be annoying to average readers, like a 90s-esque "under construction" banner.
Stubs can be mighty annoying when you're looking for something via search and all you find is a stub I wonder if it will also hurt our Google rankings? More stubs = less content = "spam" site. Do we know the impact stubs have on this (and we can't compare to Wikipedia, because we know that there is whitelisting of sites in their search engine -- see recent thread on "hacker news" in where they were not #1 any longer and Matt Cutts, search maestro/webspam dude at Google chimed in to help) If the benefits outweigh the potential cons, I'm all for stubs cheers, -c -- 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/
On Wed, 2011-11-30 at 07:14 +0800, Colin Charles wrote:
Stubs can be mighty annoying when you're looking for something via search and all you find is a stub
I wonder if it will also hurt our Google rankings? More stubs = less content = "spam" site. Do we know the impact stubs have on this (and we can't compare to Wikipedia, because we know that there is whitelisting of sites in their search engine -- see recent thread on "hacker news" in where they were not #1 any longer and Matt Cutts, search maestro/webspam dude at Google chimed in to help)
I'm afraid I don't have a good answer to this. Wikipedia has stubs, but it's reached a critical mass where a scattering of blank pages can't really hurt it. We stub a lot in GNOME, but we do things very differently. Our help is stored in git, installed along with the software, and published as HTML on the web. Our stubs never leave git, so only contributors ever see them. -- Shaun
participants (6)
-
Bryan Alsdorf -
Colin Charles -
Daniel Bartholomew -
Federico Razzoli -
Peter Lavin -
Shaun McCance