ρ (rho) wrote in lj_userdoc,
ρ
rho
lj_userdoc

Everything you ever wanted to know about lj_userdoc but were afraid to ask

I AM NO LONGER A DOCADMIN, AND THIS DOCUMENT WILL NOT BE UPDATED FURTHER. FEEL FREE TO READ IT, AS MUCH OF THE INFORMATION MAY STILL BE CORRECT OR RELEVANT, BUT PLEASE DO NOT CONTACT ME ABOUT IT, AND DO NOT TAKE ANYTHING HEREIN AS CANONICAL. THANK YOU.

lj_userdoc has various policies, procedures and guidelines, but for the most part, they're only codified in the heads of people who have been around long enough to get to know them all. This is far from an ideal situation, so this is my attempt at providing a FAQ about how lj_userdoc works. This is FAQ as in "thing that gets posted here and then linked to in the userinfo" and not FAQ as in "thing to get added to the main LiveJournal FAQ", you understand.

For now, if you have any comments, questions or constructive criticisms, please comment here. Then after a few days I'll edit the post to take this on board, and anyone with further questions will be instructed to make new top level entries.

There's nothing new here: it's just a collation of a whole bunch of existing information.



What is lj_userdoc?

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.

What is lj_userdoc not?

The following things have more appropriate places where they can be discussed, and should not be discussed in lj_userdoc:

If you do not understand the FAQ, or require technical assistance with LiveJournal, you should not ask here, but in the support area.

Updates and suggestions for howto and s2howto should be posted to howto_userdoc.

Updates and suggestions for documentation concerning the LiveJournal server, and other documentation aimed at admins or programmers should be posted to lj_sysdoc.

Wording issues of most LiveJournal pages that are not documentation related should be posted to lj_english.

Anything about the FAQs in languages other than US English should be posted in either lj_translate or the appropriate lj_ community for the language in question.

Questions about how individual FAQ questions should be referenced in support answers should be asked in learn_support. If you are interested in support, you should also watch lj_support where relevant announcements will be made.

How does the FAQ update process work?

Typically, there are three stages to a FAQ update. Firstly, 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.

Then comes a stage of discussion, which will last for at least 48 hours. During this time, people can agree with the change, disagree with the change, suggest alternative wordings, 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.

There are two exceptions to the 48 hour rule. The first of these is typos or other minor errors. In these cases the error is obvious and apparent, and the fix is simple, so there's no need to leave it open for discussion. The second is the addition of new features to the site, which either need documenting, or which make existing documentation incorrect. In these cases, it's considered best to get something broadly accurate into the FAQ as soon as possible, and then to have the more detailed discussions over exact wording, what information is required and so on afterwards.

Finally, one of the documentation admins will look over the entry, and then make any changes that need to be made. Generally, this 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, but typically, one of the editors will go through the community periodically, making any changes suggested in recent entries older than 48 hour. This generally happens about once every week or two, but can sometimes be more or less frequent. You can find an automatically updated list of who has the faqedit privilege here, but please don't hassle any of these people individually: all questions and queries should be posted to lj_userdoc.

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. 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 relative 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 is an old document though, and while it is periodically updated, it sometimes contains omissions or inaccuracies, where policies have shifted over time. As such, it should be considered only as a set of guidelines, and not as a canonical set of rules.

Anything else?

Is there anything I've missed out, or any other questions that you have about how the userdoc process works? If so, please post your question to lj_userdoc itself, and a crack team of trained monkeys will be along soon to answer you.
Subscribe
Comments for this post were disabled by the author