The state of docs
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![[profile]](https://www.dreamwidth.org/img/silk/identity/user.png)
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.
![[staff profile]](https://www.dreamwidth.org/img/silk/identity/user_staff.png)
mark stole my thunder a little by mentioning this in the main update over in ![[site community profile]](https://www.dreamwidth.org/img/comm_staff.png)
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 ![[livejournal.com profile]](https://www.dreamwidth.org/img/external/lj-userinfo.gif)
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 withmark 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 ontomark 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.
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.
no subject
Also, one thing that I want to do with the new FAQ system is to build accessibility considerations into it from the start to make it easier for us to produce accessible FAQs without the documentation writers actually having to be constantly keeping accessibility in mind. For instance, I believe that it's good practices to include a title attribute in all <a> tags, so I try to do that whenever I'm writing docs, but it's easy to forget about. So in the new system, I want for the system to automatically figure out what page I'm linking to (providing it's an on-site page) and add in the title attribute with the name of the linked page.
I'm really not sure what we need to be doing on that front, though, since accessibility has never been one of my strong points. I'm going to need input from the accessibility team on this one to let us know what we ought to be doing.
no subject
http://wiki.dwscoalition.org/notes/Accessibility_Wishlist#documentation_wishlist
I doubt any of them are quick fixes. Basically they break into two large sets: documentation for end users, which might possibly be quick to put together, and documentation for developers, designers, documentation writers, etc.
I think the accessibility team will be thrilled to contribute to thinking about what is necessary with the new FAQ system. To be honest, the first thing I think of is making it easier to find FAQs.