Forum OpenACS Q&A: Response to User Documentation

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.