[wiki] Wiki editorial: A proposal for a new docs quality process

Destry · 2011-02-18 16:05:35

In thinking about the issues raised over here, I thought it might be a good time to introduce an idea I’ve been pondering for a little while. Pondering as in… will these folks go for it or not, and if you think not, self, then why bother proposing it.

But that thread makes it clear I’m not alone knowing there’s a problem and so here’s my pitch:

Recapping, the problem with our current model (if you will) about maintaining docs is that we passively hope people will fix/update copy and links as time goes by and people stumble over the issues. While that does happen to a minor extent, it never happens significantly enough for good documentation. For a community of this small size, and even fewer of which log in to the wiki at all, counting on that process to work is like counting on money to fall out of the sky.

For us, there needs to be more of a systematic way to do it. And I don’t mean just checking for broken links with some script, because like Maverick pointed out in that other thread (and what many of us already know), there’s editorial work needing done too.

We can take a lesson from wikipedia here and consider the page adoption model. What I propose we might consider trying for a while is a content stewardship process, where people essentially take responsibility for given wiki page(s) and maintain those pages over time. This could even be a set of related pages, like all pages concerning the Content panel, or all tag pages beginning with “a”, or whatever. However people wanted to share the load best.

Here’s a glimpse of how that might work:

An inventory of the wiki is started as a google spreadsheet and made public for stewards to maintain. A living document for sure. We can start out slow by first recording the pages that have stewards, and then grow it to show what pages need stewards.
Anyone starting a new page would automatically be the steward for that page (this would go for translated pages too), unless they wanted to give stewardship to someone else, in which case they would have to name that person in the “Discussion” side of the wiki page.
Admins (e.g., me and others) who are in charge of locked pages would naturally need to be stewards of those pages.
For existing pages, we can trace the page creators and see how much they are willing to take responsibility for. We can’t expect them to carry the load if they’ve created a lot, so we’d need some kind of adopt a page process in place for all the needy offspring (see #1).
Stewards would be gently instructed about the forthcoming style guide, how to apply it’s principles, etc. (Note to self: finish the baseline of the docs style guide you’ve started.)
Stewards would continue to use editorial aids like the flags to let doc users know what the current status of the page is.
Readers and other doc users could propose to stewards content to include the the pages, as well help point out editorial flubs, technical corrections, or whatever. These ideas would be added to the associated Discussion pages where they were centralized and itemized for the stewards to address easily. (It makes no sense to keep jumping back and forth between wiki and forum for documentation development. That just disperses the focus and effort. Anyone can “watch” a given page, normal or discussion, and get email notifications when changes are made, so it’s a no brainer to follow conversations in place in the wiki in context to the page they belong to.)

You get the idea. There might be other details to work out but nothing we shouldn’t be able to handle and not complicated either.

It should be easy to see that by operating docs under this model, we more readily weed out the ROT (redundant, outdated, trivial) content, as well make sure links are valid and so forth. This could even, dare I say it, become fun for people and make it easier to see/know how to contribute. When faced with a complete wiki, nobody knows what to do, but when they know they have a given page or few to maintain over time, it takes the guess work out of it and maintenance becomes easier.

All thoughts welcome.

Destry · 2011-02-25 23:34:10

Ha-ha! Well it’s been 90 views and almost a week and not a single bite. I’ll take that as a big emphatic no frickin’ way!

That’s fine with me. Can’t blame a chap for trying. Soldier on, soldiers.

els · 2011-02-25 23:45:33

Oops. I read it last week and I quite liked your idea, I just didn’t have the time to think it over properly and reply right away; then forgot all about it… I still don’t have much time, and I still like the idea :)

maverick · 2011-02-26 00:33:54

Sorry Destry – I didn’t see this until today.

Please don’t interpret obscurity and/or apathy as “no” :)

Your proposal seems well founded.

To make it crystal clear to myself – under a content/page stewardship approach, any changes for a page would always go through that pages steward? No direct edits from the general populace (though that is not happening very much as you have noted.)

So, the important question: who makes the call and who moves this forwarded?

maverick · 2011-02-26 00:41:49

Destry wrote:

Readers and other doc users could propose to stewards content to include the the pages, as well help point out editorial flubs, technical corrections, or whatever. These ideas would be added to the associated Discussion pages where they were centralized and itemized for the stewards to address easily. (It makes no sense to keep jumping back and forth between wiki and forum for documentation development. That just disperses the focus and effort. Anyone can “watch” a given page, normal or discussion, and get email notifications when changes are made, so it’s a no brainer to follow conversations in place in the wiki in context to the page they belong to.)

I agree . . . but tempered by experience . . .

For example, I started a thread on the forum trying to pull together the collective wisdom on Multi-site installs, to create the content for a wiki page. My rational was that all though the wiki is collaborative and ideal for this, there’s not enough visibility (traffic) for successful collaboration. As is, there was only one edit last time I check (shout out to jsoo!)

If we struggle to get participation on the forum with these types of discussions, how do we successfully move the discussions to the wiki?

Just thinking out loud . . . .

jsoo · 2011-02-26 02:27:54

Sorry Destry, like Els I had read your original post, thought “hmm, this needs some thought before I reply”, then lost track of the topic.

Agree completely that the current model of expecting readers to edit or at least make public note of needed edits etc. isn’t working. I’m wondering if the whole notion of a traditional Wiki — by nature decentralized — is wrong for us. It needs to be much easier to flag items for editorial attention, and (as you say) admins/contribs need to have a centralized task list.

Instead of an adoption/ownership model I’m wondering about more of a software development model, with version control and a central issue tracker, as some projects use for their documentation. I haven’t thought this through; just thinking out loud here. My concern about the adoption model is that people tend to only take care of “their” pages. Still better than what we have now; I’m just wondering if we can go farther.

michaelkpate · 2011-02-26 04:14:07

One of my frustrations over time as a Movable Type users was that if you googled how to do something, you ended up finding what you thought was the answer – but then you realized, it was an old page and the information really didn’t apply to the latest version. I think that actually helped WordPress to be successful for a time, but they are facing the same problem.

I think good documentation is one of the key factors that helps separate successful open source projects from those that fall apart quickly. I would be glad to help if we can figure out a model that works.

Destry · 2011-02-26 18:14:01

Thanks for the replies, people.

maverick wrote:

If we struggle to get participation on the forum with these types of discussions, how do we successfully move the discussions to the wiki?

It’s a good point, and I know what you mean about not enough traffic. I suppose it would fall on the given page steward to also serve as the discussion coordinator; doing things like ensuring people watch the page is a big first step, because if they do that they get the email notifications. A large part of it, I think, is just encouraging new habits, and to do that it often means someone has to be on top of the discussions, seeing them through to completion, guiding/reminding people, etc. A lot like forum moderation, actually.

Btw, that thread on the multi-site topic was an excellent idea, and you approached in the best way under our current situation. Kudos. I think the only reason it’s not gotten far is because, like me, nobody knows what to say or doesn’t use that feature at all. Maybe forays in to documentation topics like this are a good way to pass information to devs saying ‘Hey, this feature…nobody gives a crap. How about we drop it.’

maverick wrote:

To make it crystal clear to myself – under a content/page stewardship approach, any changes for a page would always go through that pages steward? No direct edits from the general populace (though that is not happening very much as you have noted.)

That’s a good question. I didn’t mean for it to sound like that was the rule. I think putting too many rules in place, or rules that are too stiff, could turn people off and that doesn’t help either. In this case, I’d be inclined to say people could go ahead and edit directly in place. The steward would then follow up with questions, if it was even necessary, or whatever. It’s my observation that there are some people who only like to give ideas and not actually do the changes. Others don’t mind getting in and making a couple of edits. I think both should be allowed for, but the steward is ultimately responsible for making sure the final result is clear, accurate, etc. This would also mean the steward would have final say over how something was worded, etc, but naturally (s)he would be guided by the documentation style guide like anyone else.

jsoo wrote:

1) Instead of an adoption/ownership model I’m wondering about more of a software development model, with version control and a central issue tracker, as some projects use for their documentation. I haven’t thought this through; just thinking out loud here. 2) My concern about the adoption model is that people tend to only take care of “their” pages.

I numbered the main thoughts there to address them separately…

1) While I’m not completely against the idea of trying something new, I’d like to make sure we explore soft solutions first, because when it comes to problems with documentation development (we could say content development, in general), the underlying technology is rarely the problem (outside of usability), and changing it can often create new issues on top of the old ones. In a sense, the wiki has versioning by way of page history, diffing, rollbacks, etc. As for issue tracking, what I’m proposing above is really a soft approach to that very thing. Instead of people filing bug reports, they making comments in the discussion page (or making changes directly). Instead of devs fixing code and closing tickets, the stewards are leading change discussions and edits. I don’t think tech changes are the issue for us, outside of general upkeep, maintenance, use of valuable extensions, etc.

2) Taking care of their own pages is kind of the idea, and for the reason you recognize…the current situation isn’t working either. But similar to what I was saying to maverick, we should not make unnecessary rules. In this case, it should be understood that stewardship is (at the minimum) a process for ensuring pages that have stewards are well-maintained, but the old wiki model, and particularly for pages that don’t have stewards, is still in affect by necessity.

Destry · 2011-02-26 18:16:12

michaelkpate wrote:

I think good documentation is one of the key factors that helps separate successful open source projects from those that fall apart quickly. I would be glad to help if we can figure out a model that works.

I agree with that 100%, Michael. If this stewardship idea rolls forward, even just to test it out a while, maybe you can be the steward of a page or few. Take your pick. :)

Last edited by Destry (2011-02-26 18:16:47)

Textpattern CMS

Textpattern CMS support forum

#1 2011-02-18 16:05:35

[wiki] Wiki editorial: A proposal for a new docs quality process

#2 2011-02-25 23:34:10

Re: [wiki] Wiki editorial: A proposal for a new docs quality process

#3 2011-02-25 23:45:33

Re: [wiki] Wiki editorial: A proposal for a new docs quality process

#4 2011-02-26 00:33:54

Re: [wiki] Wiki editorial: A proposal for a new docs quality process

#5 2011-02-26 00:41:49

Re: [wiki] Wiki editorial: A proposal for a new docs quality process

#6 2011-02-26 02:27:54

Re: [wiki] Wiki editorial: A proposal for a new docs quality process

#7 2011-02-26 04:14:07

Re: [wiki] Wiki editorial: A proposal for a new docs quality process

#8 2011-02-26 18:14:01

Re: [wiki] Wiki editorial: A proposal for a new docs quality process

#9 2011-02-26 18:16:12

Re: [wiki] Wiki editorial: A proposal for a new docs quality process

Board footer