![[site community profile]](https://www.dreamwidth.org/img/comm_staff.png){kind=small}
So you want to write docs?
Jun. 10th, 2010 05:57 am![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
rhoA 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.
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.