Dreamwidth Documentation

An astounding thing happened while I was sleeping last night. We reached the stage where all translation strings (except for FAQs, which are handled separately) have been marked as updated! If I'm counting right, that's 3752 translation strings updated to match our terminology and our style. Almost all of them have been proof-read as well. There are still a few left that haven't, which I'm sure the copy editing team will get on soon. This means 4 things:

1. The team of people who have been working on this are completely and utterly awesome. I cannot express in words how floored I am by the work that they've done. Before we started, I'd had nightmare visions of spending 36 hours straight wrestling with the translation system to try to get things finished by Open Beta. Instead, we finish with almost 3 weeks to spare. Please, everyone join me in giving mad props to the site copy and copy editing teams!

2. This means that if you see any instances of "LiveJournal" or "Friends" or anything else that doesn't belong, then that means that it's a bug. For along time, when people have been asking, I've been saying "yeah, we know there are still a bunch of places like that; we'll get to it!" Now we've gone through the whole site, we should have fixed everything. I'd be surprised if there weren't a couple of instances that we've managed to miss though, most likely through text that's hard-coded into the system. If you spot anything that doesn't look right from here on in, please let me know. Comment here, or send me a message.

3. We need to figure out what to do now! If you want to take a break, then please do. You've earned it. However, since we have the time, I want to go back and try to polish everything up and make it all really really shiny. This is the sort of task that can never truly be finished. There are always bits of wording that can be improved, always ways to make things clearer or more concise. That's what I think we should aim for now.

So, site copy people, you now have carte blanche to go back through updated strings and be really really picky with them, and try to get them to be just so. I'd suggest that the best way to do this would probably be to trawl around the site, and look for wordings that you don't think are as good as they could be, then use ?uselang=debug to find where they come from and then go in and edit them. If you prefer some other method, though, go with whatever works best for you.

When you update things, keep them marked as updated, but uncheck the "proofed" box, so the proof readers know they need proof reading again. Proof-readers, your job remains the same as ever.

4. denise and I agree that everyone who's been involved in this herculean task deserves an invite code or two for their efforts. Go check your codes! If you haven't got any and you should, poke me and I'll go and nag Denise until she gives you some.

And finally, let me say "thank you!" again. You all rock my socks so damn much.

This entry isn't really going to be saying anything concrete. It's mainly just me putting some of my thoughts onto pixels. I'd very much appreciate any thoughts that any of you have on this, though.

At various points, from when I first took over the documentation project to this morning, I've had various people expressing an interest at getting involved with FAQs/copy/proof-reading/whatever and I've had to turn them down, for one reason or another. It breaks my heart a little bit every time I've had to do that, because I really firmly believe that everyone has something useful to offer and everyone should be able to concentrate.

The problem, for now, is that expediency is trumping pretty much all other concerns. We have a bunch of things that we need to get written by Open Beta, and getting them written is my priority. Paradoxically, asking more people to contribute at this point would be counter-productive to this goal. Time spent training people up to write in our style and to use our tools would take away from the time we have to actually write things.

In choosing my teams, one thing I was looking out for was people who I thought would be able to get writing with minimal training: people who were self0sufficient in learning new skills, for instance, or people whose natural writing styles mostly closed matched the Dreamwidth style.

Fortunately, writing documentation is a lot like writing a book. It's impossible to ever finish. There'll always be some wording that could be made clearer, some feature that isn't documented properly, or some new way of presenting things. No matter how good our documentation is, we'll always be able to make it better.

As we move on after the Open Beta launch, I want to try to bring as many people as possible into the process. The development team are doing a wonderful job of getting new people involved and training them up (dw_dev_training for instance) and I want to use what they're doing as a model for what we can do over here.

One of the problems will be that we don't have the same tools as the devs do. We don't have any nice mechanism for people to submit patches to update site copy or FAQs. We have just two options: either we can say "hey, I think that this should say this instead" or we can put it actually live on the site. This is less than ideal.

In the long-term, we're going to be scrapping the existing FAQ system and translation system and replacing them with new, better systems of our own devising. One thing that I'm keen on working into the new system from the start is some decent form of version control. I want for us to be able to make changes and have them sitting in the back-end where we can look at them, and then to be able to put them onto the live site when we're happy with them.

For now though, that isn't an option, so we'll have to figure out some other way of doing things. One possibility is to let everyone who's interest make suggestions for additions and improvements, but instead of just saying "yes" or "no" for us to then work with you to let you know why we think it's a good or a bad idea, how you can improve your suggestion, and so on. That way, hopefully, we'd be able to have people improve, and eventually reach the point where they'd be the ones who are giving the advice and making the actual changes on site.

I'm not really sure what the best way to try to organise this will be, nor even if it's going to be a good idea to have any sort of formal organisation at all. I just know that the general idea of bringing more people into the fold is one I'm committed to.

So what do you think? If you're currently on the team, how would you feel about helping to train up new people? If you aren't currently on the team, what would be most useful to you and make you want to get involved?

I'm sorry for not clarifying this before. When you're dealing with site copy stuff through the translation system, leave the FAQs alone for now. A lot of them are still being rewritten by the FAQ team, and when they are all written, we'll be handling them separately. Thanks.