ivorygates: (GEN WIKIPEDIA)
[personal profile] ivorygates
Now that we're in Open Beta, we're getting to see how actual people who aren’t us are using the site, and this is letting us know how we need to revise our documentation and, of course, write more.

One of the things we're viewing with enthusiasm now that many of our tasks are no longer as time-critical is the opportunity to allow many more people to participate in our process. In the past several months, a lot of people have wanted to get involved in site documentation, but there were a number of reasons we couldn't accept all the help that was offered.

We have now remedied that small problem.

The new community [site community profile] dw_docs_training is intended as a dedicated work and training environment for new volunteers, experienced members of the docs team, and for anyone who's working on related aspects of the GUI, such as the site copy team and the site styles team. [site community profile] dw_docs_training will be a closed, moderated, response-screened community so we can concentrate on the training and support aspects of docs writing.

In [site community profile] dw_docs_training, we'll expect you to write material off a supplied prompt and we'll the result in the community for critique. To ensure the critiquing process remains useful and focused, your sample exercises will be re-posted by one of the community moderators, and all comments will be unscreened at the same time, and only when everybody who needs to comment on the entry has commented.

Your material will be judged by three criteria: accuracy (does the site behave in the fashion you indicate?), clarity (can an inexperienced or confused reader understand what you've written and follow any directions included?) and conformity with the Dreamwidth style as laid out in the Manual of Style.

If you are participating in the community as a proofreader or copyeditor, the procedure you'll follow will be similar, except you won't be posting entries, you'll be commenting on the entries of others.

In addition to participating in [site community profile] dw_docs_training, all volunteers in training will be expected to read all of the FAQs. Not only will this give you a broad familiarity with the documentation, there are many places in which it hasn't yet reached perfection: this will be your chance to see if you can find errors.

You'll also need to familiarize yourself thoroughly with the Dreamwidth Manual of Style and the Dreamwidth Site Terminology, both of which can be found on the Dreamwidth Wiki.

The Dreamwidth Manual of Style:

The Dreamwidth Terminology Notes:

What we want out of this process, and we hope you want it too, is for you to be able to write a FAQ or other piece of site copy to site standard language, or (if you aren't one of our writers) to be able to review a piece of site copy, detect typos and other problems, identify those areas in which it does not meet the Dreamwidth standard, and prepare useful revision notes for its author.

We'll be posting the details of how to apply to the Docs Team here in [site community profile] dw_docs very soon.
[personal profile] rho
I have been neglecting you. Have kept having various things that I've meant to post here, but somehow never managed to find the time to be posting them. This is the result.

1. Site copy people! We have a fan! I received this in an email the other day:
I've just spontaneously squee'd at rah about the DW site copy and she says
you're the person to pass it along to. So forgive me if I become a little
incoherent here: god, I *love* it. Love it, love it, *love* it. *Wow* do I
love it. I click around to hunt something down and I wind up on a page
that's got information, it's got useful information, it's got clear
information, it sounds like it was written by a human being, and a helpful
and *knowledgeable* human being. (Also, and I've only just begun to
realize how hard this in particular must be to achieve, it doesn't make my
question sound dumb, and it doesn't make it sound like it'll be hard to do
whatever task it is I'm trying to do.)

It's, um, possible I may have clicked on a few links I didn't need just so
I could read a little more. Um, you know. As one does.


I know what we do can often be frustrating because it feels as if we're just invisibly moving things about in the background, with nobody ever noticing us or thanking us, so I thought I'd pass this on to you (with permission) in the hope that you all get as much of a kick out of it as I did. We're doing a kick-ass job, and I'm proud of what we've accomplished.

2. FAQ editors, if at any point you see a FAQ that we don't have yet but that you think we need, but that doesn't really seem to fit into any of the existing categories, please throw up a quick and dirty FAQ in the misc category, and then we can polish and categorise later, depending on what ends up there.

3. When you need to reference an example domain in any site text or documentation, use example.com, which is set aside specifically for the purpose. I've seen one or two people using website.tld, which I'd rather avoid because I don't think that's as obvious to non-technical people.

4. When we first went into closed beta, I decided that I'd keep membership here open, since the only people coming in at the start of closed beta would be people working on the site. We're now well into the stage of accepting users, and open beta is almost upon us. However, we've had a bunch of people join the comm and absolutely no problems so far, so I'm going to keep membership open for now, and revisit in the future if we do have any problems.

5. I'm lousy at tagging. 9 times out of 10, I forget to tag an entry, and on the tenth time, I can never figure out what tag to use. I've opened up tagging to all community members. If someone wants to go back through old posts, tag them, and come up with a coherent tagging system, I'd very much appreciate it. Once we have a robust tagging system in place, I'll probably restrict the creation of new tags down to community admins.

6. I'm fairly sure I had something else I meant to say, but I can't remember it. If I end up posting another entry in 2 hours, then I apologise.
ivorygates: (Default)
[personal profile] ivorygates
1. Now that we're down to being enormously picky here on the docs team, don't we need our own irc channel, huh huh huh? really? huh?

2. Is there a DW Comm for making suggestions? I don't actually have any suggestions right now, but I was wondering if there was an existing comm, because if there is, I'd like to link it in [community profile] dreamchasers.

3. Is there a DW Comm for asking really dumb questions? Okay, yeah, in theory there aren't any stupid questions, but in reality there are. But shouldn't there still be a place where people can ask them? (Less fuss, less muss, less work for Mother if they're all in one place, and all questions aren't Support Questions, yanno.) And (you guessed) if there is, I'd like to link it in [community profile] dreamchasers.
[personal profile] rho
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 ([site community profile] 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?
Page generated Sep. 19th, 2017 01:41 pm
Powered by Dreamwidth Studios