The state of docs

[rho]

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.

Comments

[jadelennox]

1. You are amazing and hard-working and etc. <3
2. By "you" I mean all of you awesome documentation people.
3. The accessibility team has been gathering a list of things we think should be in documentation. How should we address that with you? Or should we wait until after the FAQ system is rebuilt? It hasn't been a priority as yet.

[rho]

Let me know about it however, whenever. Email would be fine, or post here, or whatever. Depending on what the issues are, I may be able to fix them quickly, or I may suggest that we leave something until after the new system is in place. Either way, it can't hurt to know sooner rather than later.

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.

[jadelennox]

awesome. I just spent a lot of today pulling together lots of discombobulated thoughts and conversations into a more detailed set of wiki pages:

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.

[delight]

I WILL ACTUALLY DO STUFF LIKE I AM SUPPOSED TO SOMEDAY I PROMISE. :(

[stultiloquentia]

I'm psyched to hear from you! I'd been feeling sort of guilty, myself, because I signed up to turn support queries into FAQs and then flaked out on you and only wrote a few of them.

I found the great big "training sample" dumps on dw_docs_training overwhelming, especially because there was no deadline for getting them done, and they just vanished into a void. I'm game to start up again, though, once you've got your specs sorted. :)

[msilverstar]

I hope this is an OK place to report bugs.

http://www.dreamwidth.org/support/faqbrowse?faqid=82&q=name

The dreamwidth-specific tags FAQ is missing the site part of the new user tag, so new people have no way of knowing about the uber-cool cross-posting thing. <user name="msilverstar> is much less useful than <user name="msilverstar site="insanejournal.com"> as in msilverstar.

I hope you can add that in and more examples. I'd been assuming that we needed to put quotes around names, is that not the case?

[cesy]

No, quotes aren't neccessary, unless there are special characters in the name, which is rare.

[rho]

The tag itself is a link to another FAQ that has more information about the user tag, including the optional site argument. My intention was to do it that way so that the general markup FAQ was kept short and to the point, rather than trying to explain all the variants on all the tags in one place.

You're not the first person to comment on this though, so I'm guessing it's not clear. Do you think it would be clearer if I explicitly stated that each tag is also a link to another FAQ with more information?

And no, quotes aren't necessary in the user tag. You can use them or not use them as you prefer, and it makes no difference either way.

[azurelunatic]

Got a November suggestions thread?

http://www.dreamwidth.org/support/faqbrowse?faqid=120 -- should probably include the new official comms symbol too.

[yvi]

*joins you*

http://www.dreamwidth.org/support/faqbrowse?faqid=103 could do with a link to http://www.dreamwidth.org/support/faqbrowse?faqid=155 , which in turn could do with a link to http://www.dreamwidth.org/support/faqbrowse?faqid=82