lj_userdoc is a community for the discussion of LiveJournal end-user documentation. In practice, this mostly means the LiveJournal FAQ, although other pages are occasionally discussed. Additions and modifications to the FAQ are almost all discussed here before they are made. This community does not handle:
*
howto and s2howto (see howto_userdoc instead)* LiveJournal server documentation (see
lj_sysdoc)* Wording issues of non-FAQ LiveJournal pages (see
lj_english)* FAQ content in languages other than US English (see the appropriate lj_language community)
How does the FAQ update process work?
First, someone will post to
lj_userdoc, making a suggestion for an addition or correction to one or more FAQs. This can be anything from a minor nitpick over the clarity of a wording, to the suggestion of an addition of a whole new FAQ category.Once the entry is posted, members of the community can discuss the proposal: agreeing, disagreeing, suggesting wording, and so on. The aim during this time is for a group consensus to be reached over what changes, if any, should be made. This is important, as other people will often see things that the original poster missed, and can improve the suggestion, or point out why it's a bad idea.
Docadmins may choose to make the suggested changes (or reject the proposal) at any point. Generally, the changes made will be in accordance with the group consensus, but occasionally, it is necessary for an "executive veto", if a proposed change is well received, but has an underlying problem. There's no set time frame for how long an entry will sit before the FAQ get edited; however, if your proposal hasn't been addressed in 10 days, please post a reminder to
lj_userdoc.You can find a list of who has the faqedit privilege; those with * as the argument can handle FAQ changes in all categories, while those with a specific argument can only handle FAQ changes in that category. However, please don't hassle any of these people individually unless they give you permission otherwise -- all questions and queries should be posted to
lj_userdoc instead.Who can help?
Absolutely anyone can help. Ideally, you should have a good command of the English language, and detailed knowledge of how LiveJournal works, but even if you don't then you can probably still help; we need people to notice problems in the FAQs and to propose additions, just as much as we need people to actually write drafts. Many of the people who contribute are also active in the support area, as this allows them to see first hand what questions are being asked, but this is by no means a requirement. If you're interested in contributing to the FAQ, then please do so.
So how can I help?
The best way to help out is to dive right in. You might want to watch the community for a week or two to get a feel for how it works, but beyond that, just go for it. Your suggestions might not be implemented at first, but on the other hand, they might be, and either way, you'll gain insight as to how the process works, and what sort of updates are desirable. If there's a part of a FAQ that you think needs improving, then tell us about it. This could be a wording that you think is ambiguous, a bit of information that you think is missing, or anything else. Ideally, you should also suggest an improved wording that solves your problem, but if you don't have time, then you don't have to. Don't worry if you don't think your wording is very good, as it will generally serve as a useful starting point for discussion.. Similarly, don't feel bad if people want to make changes to your wording. The FAQ is a huge collaborative effort of over 65,000 words, with many hundreds of authors. There's no such thing a a perfect wording, and we always strive to make things better. Every little helps.
If you can't think of anything that you think needs changing, then you can join in on discussions of other people's proposed changes. If someone suggests a wording you find clumsy, then comment to that effect. If someone makes a suggestion, but doesn't suggest a wording, then write up a suggested wording of your own and comment with it. You should generally read the comments on an entry before making suggestions though, just to make sure that your effort isn't duplicated.
Similarly, if you're thinking of proposing a major change (such as a new FAQ, or a major rewrite from scratch of an existing one) you should generally post to the community beforehand saying what you're planning to do, to make sure that there's support for it. There's nothing more frustrating than putting in a lot of effort writing something to only then discover that there's a good reason why things are the way that they are.
What should I look out for when writing FAQs?
The main thing to keep in mind when writing documentation is to keep it simple. The FAQ as a whole serves a dual purpose: it's a reference manual that completely explains all sorts of LiveJournal related information, and it's a quick look-up tool that people can use when they want to know the answer to a specific question. These two goals are conflicting. For the first, we want to include as much information as possible, whereas for the second, we want to keep things simple so that it's easy to look things up.
The general way we handle things, which we've found to be the best way, is to include relate information, but to try to do so with as much brevity as possible. Don't go overboard with information. Before including anything, ask yourself how many people are going to find it helpful or relevant. If the answer is "not very many" then consider leaving it out. Also aim for simplicity in wording. Never use five words when one word will suffice. "LiveJournal is an online journaling site" is infinitely preferable to "Please note that the purpose of LiveJournal is to be an online website on the Internet on which one may keep a diary, journal, blog or other periodically updated material of your choosing." Try to also make sure that the most important bit of a FAQ is the most prominent, so that a reader won't have to search for it.
It can be somewhat tricky to find the art of how much is too much at first, but with a bit of practice and experience, it will start to come a lot more easily. Keep in mind the need to balance information with readability though, and you won't go far wrong.
You should also read the LiveJournal FAQ elements of style, which contains some more specific information about stylistic considerations when writing in the FAQ. This document will be updated over time, and if you notice any omissions or inaccuracies, you can comment to that entry (or post a new entry to
lj_userdoc) for clarification.Anything else?
If you have any questions about how the userdoc process works, please feel free to either comment to this entry, or post a new entry to this community.