- ([personal profile] rho) wrote in [site community profile] dw_docs2010-06-09 04:29 am

A new direction for docs

I'm the first to admit that docs has it's problems and isn't running anywhere near as smoothly as it could or should be. Part of this is down to my being busy with Real Life for the past several months, but part of it is also that the tools that we have for managing our FAQs pretty much stinks.

The system was designed on LiveJournal many years ago and it hasn't scaled well at all. One of the biggest problems, from an administrative perspective, is that there's no system in place for review and approval. Obviously, we want for anyone who is interested to be able to help with writing FAQs. Equally obviously, we can't just give anyone who shows interest the ability to edit the FAQs at will, because we need a system of quality control.

Let's say that you'd seen an omission or error in a FAQ, and rewrote it accordingly. What would then need to happen is for you to send what you've written to me, somehow, then for me to check that the change you'd made was good and then go into the FAQ admin interface and make the change. Given that the admin interface is also dated, this is something of a nightmare.

We have detailed plans for a completely new FAQ system that will solve this problem for us, but it's going to be a fairly major development project, and all our developers have other projects that are a higher priority at the moment. In the meantime, we have to make do with what we've got as best as we can.

We've tried a few different ways of organising things in the past, and truth be told, none of them have worked. [staff profile] denise and I have been plotting, though, and we're ready to bring out another approach, and we're hopeful that this time it will stick. We think this is going to be the best compromise we can make between a low barrier for entry for people wanting to get involved while simultaneously not being an administrative nightmare.

What we're going to do is start using zilla, the same system that our developers use for tracking bugs. We were slightly reticent about this, because it isn't the most user-friendly interface in the world ever, but really, once you get used to it, it's quite simple and intuitive. More importantly, it's also a mature project management tool which can make things a lot easier from the administrative end.

[staff profile] denise is going to be along shortly with a bit of a guide to zilla, and I'm going to keep the full explanations of how this is going to work until after she's posted that, but essentially, what will happen is that zilla will contain an up to date list of issues with the FAQ that need working on, anyone can assign any of these items to themselves, and once they've written the new FAQ or new version of an existing FAQ, they can upload it to zilla as an attachment and mark it as needing admin attention, at which point I or [staff profile] denise or someone else can come along and add it to the FAQ on site.

At the moment, there aren't all that many documentation items in zilla. After we decided we were going to work things this way, I just put a few of the larger, higher priority items in so we didn't have an empty list. As time goes on, I'll be putting more things in there and I'll also be soliciting suggestions here for things that need adding or changing.

We're still a little unsure of a few of the details of how this is going to work, and we'll probably change things about a little as we see things in action, but I'm confident that this is going to work so please do bear with us.

Questions are not only welcomed but also encouraged.
cesy: "Cesy" - An old-fashioned quill and ink (Default)

[personal profile] cesy 2010-06-09 07:06 am (UTC)(link)
Yay, this sounds much more easy for newbies to help out than the old system, and also much more transparent. Thank you!
liv: Stylised sheep with blue, purple, pink horizontal stripes, and teacup brand, dreams of Dreamwidth (sheeeep)

[personal profile] liv 2010-06-09 10:13 am (UTC)(link)
OK, I think this might be the impetus I need to start working on docs again. I've been a bit discouraged because I keep asking what's needed and getting no real response. If it's just in Zilla, I can work on something and someone who knows what they're doing can decide to commit, revise or reject my proposed additions and changes.
viklikesfic: avatar me w/ trans flag, spiky hair, gender unclear, fun punky glasses & sarcastic expression to go w/purple ironic halo (Default)

[personal profile] viklikesfic 2010-06-09 02:49 pm (UTC)(link)
Hello! I just wanted to chime in and say that I've really wanted to work on docs, but got the impression that no help was needed/wanted at this phase and thus have been trying to learn how to code (with limited success). If you need someone to put in a major effort on docs, I will volunteer myself. I have lots of writing and organizational experience.
adalger: Earthrise as seen from the moon, captured on camera by the crew of Apollo 16 (Default)

[personal profile] adalger 2010-06-09 03:30 pm (UTC)(link)
Question: will anyone with a bugzilla login be able to file a doc / faq bug, much like filing other types of bugs in 'zilla? This would be a smoother interface for support volunteers to call attention to outdated FAQs, too.
foxfirefey: Dreamwidth: social content with dimension. (dreamwidth)

[personal profile] foxfirefey 2010-06-09 03:52 pm (UTC)(link)
As someone who'd like to do a little docs now and again but had absolutely no idea where to start, this is awesome!
stultiloquentia: Campbells condensed primordial soup (Default)

[personal profile] stultiloquentia 2010-06-10 12:43 am (UTC)(link)
This pleases me greatly. :o)