June 4th, 2001

Work on LJ Guides to resume

I've made arrangements with daniela and mentuhotep to continue Gita's work on writing LiveJournal Guides in her absence. We received Mark's approval tonight to do this. delusionalangel will still maintain the FAQs, and we'll co-ordinate with her as necessary. I'll explain our plans in this journal as time allows.

We'll need a few weeks to get up to speed. I hope that by the end of the month, Daniela and/or Mentuhotep will be fully in charge of writing Guides unless Gita has returned.

For those who are wondering: sorry, I haven't heard from Gita since early May and don't know of anyone who has. She did complain about Internet connectivity problems several times, and I hope that nothing more than that is keeping her away.

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)
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.

Instituting a "Top-Down" Approach to the FAQs


G'day guys:

I've been thinking for a while about this, and wanted to ask your opinions. I am posting it in lj_userdoc but I have posted a link to this discussion in lj_support as well, as this affects them as well. If you're not a part of Userdoc, and have come here from the Support Community, I still would value your comments.

I've decided to ask everyone what they thought first before I got to work on this. I'd like know what everyone thought about taking a more "top-down" approach to organisation and development of the FAQs. More looking at the general areas where there are FAQs needed, and then coming up specifically with the questions and answers.

At the moment, I noticed that a FAQ gets written and posted, and as a result some areas have lots of FAQs, and some don't have much at all. There's very much a "piecemeal" approach to the FAQs, and they don't necessarily integrate well with each other. There also seems to be a lot of things that Support is repeating recently, but there are no FAQs for.

I don't want to tread on any toes here, and that's why I'm writing this post. I know that Gita (genders) was doing something on this, and I was going to get working with her, but I believe she's having problems with her ISP.

I'm wondering, how would you feel if I took on the job of trying to co-ordinate a plan for what FAQs are needed, and getting them organised, grouped appropirately by area? In some way this can incorporate in the FAQs what we hoped to achieve with the Guides as well.

I'm prepared to do this if you'd like, slowly over the next few months or so (I have exams soon, and then go studying in a rural hospital for a month, but will be able to work on it from there), and more after that.

Perhaps I could pose the questions in LJ Support (initially what areas do we need to support,
then later taking each area, asking what questions continually come up, writing a list of questions that would lead through all the aspects of that area, from the simple to the difficult, then eventually assigning the task of writing FAQs or rewriting current individual FAQs, keeping in mind which other ones are being written on the topic, then getting people to review them. I realise this is a massive task, but I do think I have the relevant skills in Project Management that would allow me to get it done in a reasonable time frame. I also believe in transparency in what I do, so at each stage I would report back to Userdoc and Support for comments.

The big question is, do you think this is useful and needed or not, and if it is, whether it would be inappropriate for me to do this?

Let me know what you think. I'm happy to elaborate if you have any questions about what I'm thinking of doing. If you think it's a bad idea for me to do it, that's fine, and I'm happy to continue as a general member of the Support community as usual.