Abe Hassan (burr86) wrote in lj_userdoc,
Abe Hassan

faq writing guidelines | RFC

I'd like to come up with a list of principles we follow when we write/edit FAQs; not "how to format the FAQ" or "stylistic rules" but rather some more general guidelines that dictate how we document what we document. To that end, I'll list off some of the principles I tend to follow -- these aren't set in stone, so feel free to tell me that you think I'm crazy *g*. I also invite anyone and everyone to comment with what their vision of the FAQs should be, and offer up guidelines of your own. I'll then pull together everyone's contributions and try to come up with something we can all agree to.

* FAQs should provide information on accomplishing individual tasks, rather than explaining site functionality. (The old vs. new versions of FAQ75 are an example: previously we lumped things together just because they were lj user tags, but to most users, that grouping doesn't make sense; instead, splitting things into the effect people want to accomplish makes a bit more sense.)

* FAQs should assume reasonable intelligence.... okay, not too much intelligence, but we should be able to assume that the reader is capable of following basic instructions. *g* For instance, some of the FAQs say, "go to this page, then click this button, then do that, then switch this option, then ..." Sometimes it makes sense or is appropriate to do that, but if someone of reasonable intelligence can figure out how a page works just by looking at it, then linking to it is sufficient; no need to explain how to use the page.

* FAQs should provide information that the typical user will care about. To that end, "someone once asked about this in a Support request in 2003" doesn't mean that piece of information needs to be documented. *g* Of course, we should document the usual things people might run into, typical gotchas, things of that nature. But if it's a fairly uncommon point of confusion, or if it's a question that the vast majority of users have no need to ask, we can probably skip it.

* FAQs should abstract away the internal workings of LJ. Things like, "and then LJ sets a cookie and the database has a value with your cookie and etc" or phrases like "load balancer" or things like that generally are too technical for the purpose of the FAQs. We should avoid that sort of language/detail, where possible.

* FAQs should discuss an individual topic/issue. I know we have a tendency to overload existing FAQs to avoid creating new ones -- I think it's okay to create new ones as long as doing so splits the information according to the way people go about doing a task on the site. (See also: FAQ75 and the way it was split up, though we didn't make new FAQs, but the point still stands there. *g*)

... And that's where I can no longer think of other things, though I'm sure they'll come to me eventually. Other thoughts/suggestions?
Tags: administrative, rfc
  • Post a new comment


    Comments allowed for members only

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded