Abe Hassan (burr86) wrote in lj_userdoc,
Abe Hassan
burr86
lj_userdoc

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. This can be considered a "living document"; I will keep updating it as further items become necessary. If you have anything to add to these, or if you'd like to clarify anything, please feel free to comment.



  • 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. Alternately, a score of 60-70 on the Flesch-Kincaid scale can also be used; some word processing programs contain modules which will calculate a document's score on this scale.

  • Capitalization: The proper capitalizations are the following: Friends list, Friends-only, Friend-Of list, Paid Account, 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 be indented within the text, and any variable elements shall be italicized. The text should clearly explain the possible values for each variable. No brackets are necessary.

  • 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" or "postings". The verb form is "to post an entry".

  • email: The term "email" shall be used, rather than "e-mail".

  • Further Reading: Links and references relevant to the FAQ shall be included within the body of the FAQ itself. If there are additional links that cannot easily be inserted inline, they shall be listed in a "Further Reading" section at the bottom of the FAQ.

  • hidden FAQs: Any FAQ which is hidden shall have its text replaced by a link to the FAQ which supercedes it, to preserve any direct links to the original FAQ.

  • Journal References: All journal references should be in the form <lj user="exampleusername">.

  • 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", and likewise for "log out". However, "login" is one word when used as a noun or adjective.

  • 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

  • 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 linked to the page itself.

  • Title formation: 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.

  • 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. The community communityname also serves the same purpose.


Tags: administrative
Subscribe

  • Post a new comment

    Error

    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 

    Help
  • 12 comments