CAPS LIKE WHOA (jc) wrote in lj_userdoc,

Policy: HTML formatting guide

We've had the ability to use HTML within our FAQs for some months now, and it was high time we developed a policy for actually using it. You guys won't generally need to worry about these guidelines as it's the docadmins and category administrators who'll actually be following them, but in the event that you contribute a draft for an FAQ it'll help to know the policy, to save us time reformatting later.

Last updated January 31st 2009: modified to include info on using warningbars for account-specific FAQs.

So, here are the ten rules you should follow when crafting your HTMLised FAQ.
  1. Section headers: No more all-caps! Yay! Instead, they'll be wrapped in <h3> tag pairs and have link anchors to boot, for easy linking within support answers.
    • Use title case, e.g. "Further Reading".
    • Use your common sense when choosing the name of a link anchor, and try and name them consistently. For example, sections across multiple FAQs that all deal with downloadable clients are named "clients", e.g. <a name="clients"></a>.
    • Space sections consistently: three line breaks between the end of a section and the following <h3>, one after the </h3>. Example:
      ...and that's how you mess up your journal.

      <a name="web"></a><h3>Using the Web Interface</h3>
      When you use the Update Journal page...

  2. Lists:
    • <ul></ul> lists for bullet points, as used in #125.
    • <ol></ol> for step-by-step instruction lists, e.g. "1. Overthrow the government. 2. ??? 3. Profit!"
    • To make lists easier to read when translating, break each list item up (using line breaks after each </li>) and enclose the list in <lj-raw> tags to prevent said line breaks being replaced by <br /> tags. If you feel that spacing out list items increases readability, such as I did when writing this numbered list, place the closing </lj-raw> tag after the first </li>. Example:
      <li>list item one</li></lj-raw>
      <li>list item two</li>
      <li>list item many</li></ul>

  3. Emphasis: Bold to point out certain things, such as the default security levels listed in the second paragraph of #255. Italics to highlight things that should be changed by the user, e.g. " - replace exampleusername with your mom."

  4. Important messages: should be relayed to readers through the use of warningbars and site CSS. Example:
    This FAQ applies only to Plus, Paid and Permanent accounts. To check your account type, please see your profile page. (→ More information on account levels)
    More info here.

  5. Dummy links: Links used for example purposes only, i.e. anything containing exampleusername (except those pages that are actually useful), to be enclosed in <lj-raw> tags so people can't click on them and complain when they're hit with a 404.

  6. Code examples: Xcolibur site CSS treats <code> and <tt> blocks as second-class citizens next to the main body text, in that text appears smaller than it should. So, none of that - just a simple <blockquote> tag pair around code examples that need to stand out from the main body of the text, overrides for example. Same for any other indents.

  7. FAQ interlinking:
    • Link phrases to FAQs as and when appropriate, such as "contact the Abuse team" linking to #105 and "voice posts" linking to #183.
    • Use the <a href="lj://faq/123"> URL form wherever possible, unless you need to link to the full version of an FAQ or an anchor within that FAQ.
    • In cases where it's not immediately obvious why you're linking to a particular FAQ, use the title attribute in your links (at your discretion) to provide visual feedback as to what that FAQ deals with, for example "More on voice posts in FAQ #183". Better yet, use the FAQ title itself:
      <a href="lj://faq/183" title="FAQ #183: [[faqtitle:183]]">voice posts</a>
      Warning: watch out for inverted commas and apostrophes in FAQ titles. If an FAQ title contains inverted commas ("), use apostrophes around the title attribute (title='[[faqtitle:70]]'). Otherwise, use inverted commas as normal.
    • Link to an FAQ in the Further Reading section only when that link doesn't belong anywhere else in that FAQ.

  8. Other interlinking:
    • When linking to another page on LiveJournal, use the translation string relating to the page title, or failing that the page title in English, as the link phrase wherever possible, i.e. "go to the Update Journal page", unless linking to more than one page with the same title, i.e. the two "Your Styles" pages linked to within #256 (which, incidentally, won't be an issue for that particular FAQ once ljkrissy's fix goes live).
    • Where a page is mentioned more than once in a particular FAQ, link the first mention in each section of the page only unless considered necessary.
    • We now have shiny FAQ variables to play with: use them! And these! For translation purposes.

  9. Further reading linking: No raw URLs, or even any FAQ titles: just a spaced out <ul> list of the variable-provided FAQ titles linked to their appropriate pages. Example:
    <lj-raw><h3>Further Reading</h3>
    <li><a href="lj://faq/207">[[faqtitle:207]]</a></li></lj-raw>
    <li><a href="lj://faq/216">[[faqtitle:216]]</a></li>
    <li><a href="lj://faq/192">[[faqtitle:192]]</a></li>
    <li><lj user="howto">: <a href="">Embedding: HTML Frames</a></li></ul>

  10. Dividers: Given that <h3> headers divide an FAQ up nicely, we might never need these: if you do, simple <hr />s should do the trick.
Tags: administrative

  • 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