Hello Kitty, Destroyer of Worlds (rahaeli) wrote in lj_userdoc,
Hello Kitty, Destroyer of Worlds

LiveJournal FAQ Elements of Style

The following conventions should be used when writing or rewriting FAQs. This is to ensure consistency with the other FAQs. (And yes, many FAQs do not follow these conventions; this will change.) For FAQ editors: if you are making another change to a FAQ and you note that some parts of the FAQ do not follow these guidelines, go ahead and make the changes while you are editing the FAQ; however, don't bother going through all of the FAQs looking for stuff that doesn't comply.

This will change with the new FAQ structure, which will happen soon (target date for this patch is mid-January). Until then, this structure should be used for all new FAQs and all edited FAQs.

This can be considered a "living document"; I will keep updating it as further items become necessary. Anyone who has suggestions to these, please let me know.

  • Abbreviations: Abbreviations should be avoided wherever possible: LiveJournal rather than LJ, Terms of Service rather than ToS, etc

  • Answering the question immediately: If a question is phrased in the form of "Can I...?" the first word of the FAQ should be "Yes" or "No". If it is "yes", consider rephrasing the question in the form of "How do I...?"

  • apostrophes: Apostrophes shall not be used for the plural of an abbreviation: FAQs rather than FAQ's, etc

  • average reading level: FAQs should have an average reading level of 8.0-9.0 on the SMOG readability scale.

  • Bulleted Items: To set off an item by bullet points, the asterisk (*) should be used for each bullet point.

  • Capitalization: The proper capitalizations are the following: Friends list, Friend-Of list, User Info page. Generally, the site page is capitalized and the word "page" or "list" is lowercased.

  • contractions: Do not use contractions in the title of a FAQ. Contractions are acceptable in the body of a FAQ.

  • Console commands: Any console commands that have variables in the example command should have brackets (< >) placed around the variable elements of the command. Underneath the example command, it should clearly state that the brackets should not be typed in the actual command.

  • crediting users: No credit will be provided in FAQs for information given. Users who provide regular updates to FAQs in the lj_userdoc community will be thanked with acknowledged contributions.

  • entry vs. post: Refer to them as "entries", rather than "posts". The verb form is "to post an entry".

  • Horizontal Rule: If the text of the FAQ is such that a horizontal rule will allow for easier visual presentation of the information, it should consist of ten spaces before, and one asterisk (*) making up the horizontal rule. A blank line should follow before and after the horizontal rule.

  • Hyperlinks: When used in a fashion that's parenthetical to the actual sentence, hyperlinks should be enclosed in parentheses (). There should be no space between the opening and closing parenthesis.

  • Journal References: All journal references should be in the form http://www.livejournal.com/userinfo.bml?user=exampleusername; this will allow a reader to easily add the journal to his/her friends list.

  • LiveJournal: The site's name should be properly capitalized in all instances and be fully spelled out (rather than using LJ)

  • login vs. log in: This should always be two words when used as a verb: "log in" rather than "login". The same for "log out".

  • non-official journals, references to: Non-official journals should never be referenced in FAQs.

  • offsite links: Offsite links should never be used in any FAQ, as LiveJournal does not control the offsite link. If there is a resource that absolutely must be included, and there is no on-site equivalent, contact one of the documentation managers for an opinion on whether or not it is acceptable.

  • parenthetical statements: When all possible, do not use parenthetical statements in the course of a sentence. If something is important enough to mention in the FAQ at all, give it its own sentence.

  • passive vs. active voice: When possible, FAQs shall be written in active voice.

  • personal email addresses: Personal email addresses should never be referenced in FAQs; rather, the site official email addresses, such as webmaster@, privacy@, support@, and abuse@ shall be referenced

  • Question formation: Questions that have an answer of "no" should be phrased as "Can I ...?" in the title. Questions that have an answer of "yes" should be phrased with some variation on "How do I do...?". FAQ titles should all be phrased as a question. For questions regarding options, where people may not be even aware of the existence of the option, questions should be phrased as "What is the foo option? how do I use it?" Questions should be as concise as possible.

  • personal pronouns, usage of: When at all possible, personal pronouns should not be used in FAQ writing. Use the site's name instead: "LiveJournal" rather than "we".

  • site pages, references to: Titles of site pages should be capitalized (see: capitalization) and should use the name that the site uses for the page. Names of site pages should be followed with an immediate link (such as "Terms of Service (http://www.livejournal.com/legal/tos.bml)"

  • variables, use of in usernames: If you need to use a variable username in a URL reference, use the journal exampleusername, which is being squatted on by a FAQ maintainer for that very purpose.

  • 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 

  • 1 comment