Forum OpenACS Q&A: User Documentation

Collapse
1: User Documentation
Posted by Malte Sussdorff on 07/11/02 09:49 AM
We are in the process of writing a user documentation for our survey module (kudos to Sloan for the feature overview, ups, RFP 😊). Here is the structure, how we want to tackle this:
  1. General Overview (what is this all about)
  2. Feature Overview
  3. One to Three use cases (overview, what the use case is all about)
  4. Step by step guide how to accomplish the use case (along with pictures, aka screenshots)
  5. Descripiton how to use not already covered functionality.
Person in charge on our side will be Venkatesh Goteti and I already asked him to contact Ben K. as he seems to be heading down to write user documentation. But maybe you have additional comments.
Collapse
2: Response to User Documentation (response to 1)
Posted by Venkatesh Goteti on 07/21/02 01:37 PM

Here's an attempt to go bang on to a few issues and possible solutions with regards to 'User Documentation.' Maybe it may sound as if we are making a big deal out of it, but as we explore it on our end at S&R, it seems to be more than just helping a user navigate around. Hence, not delving further into any diagnosis, we are planning to work on a few aspects to bridge that gap. Some of the aspects here are part of discussions we've been having, trying to define a clear-cut strategy to go about it. So, steering clear of history lessons and "Long long ago in 199X, I wrote a page...." tales, here are some thoughts:
Taking the baton from Jon Griffin's notes on the subject, we would like to work further on creating additional standards for developing User Documentation.

To begin with, so that we bite as much as we can chew at this moment, we just focus on the 'End-user' here. Keeping in mind a long term vision for the system, the proposal is to address:

  1. Issue about training: A training model (suggested) could also help in the creation of User Documentation with a dual purpose. 
  2. Types of information we need to create and possible formats (Paper-based and electronic). Here we also how define how we organise this in the form of User manuals (to teach end users how to use the product effectively), quick reference guides for advanced users, training material created to support the product (where training development includes conducting the needs analysis, and developing modules that can easily be adapted for a variety of uses and audiences and languages. The training material can be Web-based, or hard-copy format), and glossaries provide definitions for the topics discussed in the main document. Further, we also incorporate well categorised discussion forums where Users are supported.
  3. We create scope for modification of User documentation for reasons such as:
    • Enable a progressive improvement of the documentation itself and also allow to expand across lifecycles, else a lot of effort might end up useless, if we do not think ahead of this issue. Screens might change, functionalities might be modified, more added etc.,
    • A module documentation needs to be flexible and adaptable to the language to be used in an organisation, if it is to have a role in the the organisational change process and culture. Reason being that this could, in phases, help reform users' perception of the overall system. Documentation that implies heavy re-writing will end up being redundant.

Tasks and action points here could be:

  1. We have a detailed documentation strategy and plan in a way, where we identify collaborators, modules to focus on, timeline, target audiences (students, NGOs, corporates...and their related skill-sets, expected resistance etc.,).
  2. We first create an OACS Documentation Standards Tool Kit for paper based and electronic formats alike. This will allow us to co-create content in different parts and add to a central location. This works easy with code as there is a framework for developers, but this has to be created for technical writers as well. The aspects we then ought to consider here are Responsibilities, User procedures as we define them, language issues..etc.,

I'll stop at this, and would like to have some response to these thoughts. Once we set the ball rolling, I'd get back with details on how we would share a few tasks, define some interim work products, and also nail down a few timelines and phases to deliver. While we'd also like to see how contiguous issues such as how do we address the need to have category administrators if we are to set up information in categories etc.,.may I suggest that we put aside all such things on a parking lot/aside and first nail down the essentials to start with. This is merely to ensure that we do not hit a roadblock before we begin :)
More soon...till then, looking forward to some thoughts, thrashings, learnings, experience sharing around the above aspect.

Collapse
3: Response to User Documentation (response to 1)
Posted by Torben Brosten on 07/21/02 08:43 PM
Venkatesh Goteti,

Current OpenACS documentation standards exist (for 4.5) at https://openacs.org/doc/openacs-4/docbook-primer.html. As you state, the guides are specific to publishing style and do not help much with writing style standards and goals of each documentation. I'm writing a comprehensive list of requirements/goals and plans for the docs to help provide direction for completing and maintaining all the docs. My own efforts are focused on writing user documentation for the system in general (not for the packages yet). Currently, I have collected about 22 pages of notes (48k txt file) about the doc standards from the board discussions, current docs etc. in addition to other notes that may be helpful to end-users. I will post the document standards guidelines in the documentation area of the CVS (and post a message to the board) as soon as it becomes useful.

Roberto and Vinod, I'll send you copies so you have a chance to revise it before publishing also.

Collapse
4: Response to User Documentation (response to 1)
Posted by Torben Brosten on 07/21/02 10:25 PM
For the record, I just skimmed the notes about documentation that mention "package" and sent them to Venkatesh Goteti.