Tribeless Nomad (tribelessnomad) wrote in lj_userdoc,
Tribeless Nomad

What users want from documentation

Documentation should be written with the immediate needs of the user foremost in one's mind. Users turn to documentation for a variety of different reasons; for each reason, we should make information available in an appropriate form, so that it's easy to find and easy to read.

I expect users to seek out documentation as follows:
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 (Help) 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.

Guides, Help pages, and FAQs can all be cross-linked as appropriate.

So, our documentation for end users should take shape accordingly. Comments?

  • 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