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:
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.)
Title HTML (from BML) XML Getting Started start.bml start.xml Free Accounts free.bml not available yet (Update) Interests interests.bml interests.xml Support Policy support.bml support.xml
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.
