Tribeless Nomad (tribelessnomad) wrote in lj_userdoc,
Tribeless Nomad
tribelessnomad
lj_userdoc

What are LJ Guides?

At present, LiveJournal's documentation for end users consists almost entirely of FAQ pages.

In early February, Gita (genders) became involved in FAQ maintainance, and embarked on the creation of some companion documents called Guides. She told me at the time that Brad (bradfitz) thought the FAQ pages looked too much like how-to guides, and should be reduced to actual questions and answers.

FAQs are written in plain text and stored in the server's database. When they're displayed, an attempt is made to render URLs as working hyperlinks, sometimes with undesirable results. Clearly, their usefulness is somewhat limited.

Guides provide good control over presentation. They are currently written in BML, but will soon be written in XML. XML allows sophisticated formatting, including <lj...> tags. Among other advantages, the XML format makes it easier to assemble documents into a comprehensive manual, or to transform them into alternative formats.

Here are the existing Guides:
TitleHTML (from BML)XML
Getting Startedstart.bmlstart.xml
Free Accountsfree.bmlnot available yet (Update)
Interestsinterests.bmlinterests.xml
Support Policysupport.bmlsupport.xml
Both BML and XML get converted to HTML (or something) before being viewed by LJ users. The HTML looks very much the same, regardless of whether the source was BML or XML. We'll probably use the XML-based format which I'm developing, rather than BML as Gita was doing, but that decision is ultimately up to Mentuhotep and Daniela as the lead writers. (We won't commit to XML unless I can already convert it to BML.)

Once the Guides are ready, they will complement the FAQs. Gita's views on the difference between FAQs and Guides can be seen at http://www.livejournal.com/talkread.bml?itemid=3064380&thread=3649949 and http://www.livejournal.com/talkread.bml?itemid=3124307. Those posts are the latest description of her overall plan, so we're picking up from there.

I'm supposed to merge Guides and FAQs with other documents into a comprehensive LiveJournal manual. Therefore, Guides should be complete, well organized summaries of how to use each feature of the site. Think of them as sections within chapters of the manual.

Most of the content of the current FAQs will end up in the Guides. Plus, a lot of new content will have to be written for the Guides.

The Guides will contain links to relevant FAQs, which will answer specific questions. FAQs can also contain links to Guides.
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 

  • 6 comments