What users want from documentation

Manual: Some people will want a full description of the site. They might be professionals evaluating LJ's suitability for some particular purpose, or they might be eager users who want to know whether they've overlooked any interesting features. What they need is a comprehensive manual. Brad has asked for all documentation to be combined into such a manual, but the Guides will be the most important component. Once the manual is fairly complete, links to it will presumably appear on some of the site's main pages.

Tour: Most individuals, wondering whether LJ is the right place to start a weblog, won't want to read the comprehensive manual before they decide. For them, there should be a tour of the site. This will be so visual, it hardly counts as documentation, but for each page visited on the tour, there should be links to Guides describing the important features available on that page. Creating a tour is not part of the Guides project, but has been discussed several times before. The expectation that a tour will be created reduces the pressure on us to make the Guides highly pictorial.

Guides: When users want to read how a feature (such as the To-Do List) works, what they need is a Guide to that feature. They might find the appropriate Guide by looking in the manual, by following a link from the Newbies lounge or the main Support page, by following a link from a related page (such as their own To-Do List), or by following a link that someone posted (in a news journal, perhaps). The Guide should explain as simply as possible what that feature can do for them, and how to use it.

Help pages: Sometimes a user wants to know what a particular button (box, etc.) will do before using it. Clicking on a nearby Help icon () can take the user directly to a Help page with the appropriate information. I think of Help pages as distinct from both FAQs and Guides, but we have no separate format for them. They are currently stored as FAQs, but could be converted to the Guide format as part of the Guides project. Possibly the blue sidebar menu could be documented by creating a Help page for each section.

FAQs: Questions that users commonly post as Support Requests are FAQs. The list of FAQs will change over time, as the site is modified and documentation is improved. A complete list of FAQs can be seen "live" at /support/faq.bml, but a user typically doesn't know in advance whether his/her question is answered in a FAQ or in a Guide. That means we should have a single interface to all documents, which will be the support-links section of the main Support page. I'll post separately about how those links should be organized. The drop-down box that Support volunteers use when answering a Support Request should still list FAQs, not Guides. That will encourage volunteers to link to specific answers, rather than general Guides.