Dreamwidth Documentation

A quick note for those of you who don't read dw_styles: foxfirefey is planning the documentation of all things S2 over there and would appreciate any help you could give!

A few things to bear in mind for anyone wanting to write documentation for us.

1. We have a manual of style which will tell you such useful things as how you should use "email" instead of "e-mail" and how you should never use comma splices.

2. The general aim of our FAQs is to convey information as clearly and concisely as possible. This means that it's often better not to include all information possible that pertains to a subject, since that just leads to information overload. Ideally, no FAQ should be longer than about 3 or 4 paragraphs long unless there's a good reason. We want people to be able to find the information they're looking for without feeling as if they've got to read a thesis first.

3. Always aim for accessibility in everything you write, and remember that different people will be accessing the page in different ways. There are different site schemes, different styles, text only browsers, screenreaders, and so on and so forth. Saying "click the icon that looks like a bell on the left hand side of the screen" is utterly useless to people who aren't using a screen and can't see images. I'll go into this in more detail at a future point, but for now, it's something to be aware of.

4. There are various FAQ variables that you can use in FAQs to do things like show the username of whoever's viewing the page.

5. Give it a go! If you see anything in zilla that takes your fancy, assign it to yourself and give it a go. I'm happy to work with people to polish up first drafts to be more in keeping with our standards.

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. 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.

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 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.

Short summary version of this post: things have been sucking, I know, I'm sorry, we're trying to make things better, watch this space for more.

Much as I hate to admit it, docs has been a bit of a mess since we went into Open Beta. We've been behind on getting new information up, there have been a lot of people who have been wanting to help but haven't been able to, and things generally haven't been going as smoothly as they should.

As head of all things docs, I take full responsibility for this, and will accept any rotten fruit you feel like throwing at me. I deserve it. However, as a personal favour, I'd like to request that you go easy on the rotten tomatoes. I hate tomatoes.

So what's been going on, and where are we going from here?

First thing I need to report is that ivorygate has stepped down as co-admin of docs due to an excess of Real Life, so I'm flying solo again. I'd just like to stress again that any problems we're having are my fault and not hers, and thank her for all the work she's done.

On a happier note, I've just got back from a 6 week holiday, and now that I'm home and recovered from the killer jetlag of transatlantic travel, I'm finding that a lot of the burnout I'd been feeling before has gone away, and I'm viewing Dreamwidth with a brand new energy and enthusiasm again. Hurrah. My task is going to be to dig us out of the hole I've landed us in and get documentation working again.

mark stole my thunder a little by mentioning this in the main update over in dw_news yesterday, but I'd like to go into a bit more detail here. One of the big problems that we have with documentation is that the FAQ system that we're using which we inherited from LiveJournal is old, and boy does it show. It's had a few minor updates over the years, but by and large it's still exactly the same system that brad first put in place about a decade ago.

Generally, when using this system, it feels a whole lot more as if we're fighting against it than working with it, and that sucks. This is one of the reasons why there are plenty of people wanting to help out who can't. The system just isn't designed to work well with big projects requiring a lot of people. We tried various ways to try to get more people involved, but none of them really worked. I'm proud of what we accomplished for open beta, but the administrative work for that just about killed me (because of the system; not because of the awesome people) and was what led to burnout I mentioned before.

The good thing now is that with mark working for Dreamwidth full time, we're going to have the opportunity to rewrite the whole documentation system from scratch into a form that actually suits our needs and does what we want it to. One of the things that I'm trying to focus on in designing the new system is to make sure that it's as easy as possible for people to get involved. I know there's a mass of untapped potential out there from people who want to help but haven't been able to, and I really want to be able to harness that potential to make something awesome.

I'm still working on the specifications for now (for those who aren't familiar with the workflow involved here, I'll be writing the specifications for exactly what the new system should do and I'll then pass them onto mark who will write the code to actually build the system) so I don't have anything concrete to share at this point. Hopefully I'll have a first draft specifications done in a day or two, at which point I'll post them here for discussion and brain-storming.