maria-docs team mailing list archive

[Daniel Bartholomew <dbart@xxxxxxxxxxxxxxxx>]

On Mon, 05 Dec 2011 16:44:05 -0600
Bryan Alsdorf <bryan@xxxxxxxxxxxx> 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@xxxxxxxxx>  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