End-users - Req.

Documentation Requirements for End-users

By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.

OpenACS end-user documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

• End-users should not have to read docs to use the system.

• Include how to get help. How and where to find answers, contact others, what to do if one gets an AOLserver or other error when using the system. Include types of available support (open-source, private commercial etc.) including references.

• Explain/foster understanding of the overall structure of the system. This would be an overview of the system components, how it works, and how to find out more or dig deeper... To promote the system by presenting the history of the system, and writing about some tacit knowledge re: OpenACS.org and the opensource culture.

• Introduce and inspire readers about the uses, benefits, and the possibilities this system brings (think customer solution, customer cost, convenience, value). A comprehensive community communications system; How this system is valuable to users; Reasons others use OpenACS (with quotes in their own words) "...the most important thing that the ACS does is manage users, i.e. provide a way to group, view and manipulate members of the web community. -- Talli Somekh, September 19, 2001" using it to communicate, cooperate, collaborate... OpenACS offers directed content functionality with the OpenACS templating system. ... OpenACS is more than a data collection and presentation tool. OpenACS has management facilities that are absent in other portals. ...The beauty of OpenACS is the simplicity (and scalability) of the platform on which it is built and the library of tried and tested community building tools that are waiting to be added. It seems that most portals just add another layer of complexity to the cake. See Slides on OACS features...a set of slides on OACS features that can be used for beginners who want to know OACS is about and what they can do with it. Screen captures that highlight features. Example shows BBoard, calendar, news, file storage, wimpy point, ticket tracking. An OpenACS tour; an abbreviated, interactive set of demo pages.

• From a marketing perspective,

  • differentiate "product" by highlighting features, performance quality, conformance to standards, durability (handling of technological obsolescence), reliability, repairability, style of use, design (strategy in design, specifications, integrated, well-matched systems etc).

  • differentiate "service" by highlighting software availability (licensing and completeness from mature to early adopters or development versions), community incident support, project collaborative opportunities, and contractor support availability

  • differentiate price (economic considerations of opensource and features)

  • Discussion and details should rely on meeting criteria of design, completeness of implementation, and related system strengths and weaknesses. Marketing should not rely on comparing to other technologies. Competitive analysis involves mapping out strengths, weaknesses, opportunities and threats when compared to other systems for a specific purpose, and thus is inappropriate (and becomes stale quickly) for general documentation.

  • When identifying subsystems, such as tcl, include links to their marketing material if available.

  • create an example/template comparison table that shows versions of OpenACS and other systems (commonly competing against OpenACS) versus a summary feature list and how well each meets the feature criteria. Each system should be marked with a date to indicate time information was gathered, since information is likely volatile.

• To build awareness about OpenACS, consider product differentiation: form, features, performance quality, conformance quality (to standards and requirements), durability, reliability, repairability, style, design: the deliberate planning of these product attributes.

• Include jargon definitions, glossary, FAQs, site map/index, including where to find Instructions for using the packages. FAQ should refer like answers to the same place for consistency, brevity and maintainability.

• Explain/tutorial on how the UI works (links do more than go to places, they are active), Page flow, descriptions of form elements; browser/interface strengths and limitations (cookies, other)

• Discuss criteria used to decide which features are important, and the quality of the implementation from a users perspective. Each project implementation places a different emphasis on the various criteria, which is why providing a framework to help decide is probably more useful than an actual comparison.

Package documentation requirements have additional requirements.

• A list of all packages, their names, their purposes, what they can and cannot do (strengths, limitations), what differentiates them from similar packages, minimal description, current version, implementation status, author/maintainers, link(s) to more info. Current version available at the repository.

• Include dependencies/requirements, known conflicts, and comments from the real world edited into a longer description to quickly learn if a package is appropriate for specific projects.

• Create a long bulleted list of features. Feature list should go deeper than high-level feature lists and look at the quality of the implementations (from the user's perspective, not the programmer's). Example issues an end-user may have questions about: Ticket Tracker and Ticket Tracker Lite, why would I want one of them vs the other? And, before I specify to download and install it, what credit card gateways are supported by the current e-commerce module? There are some packages where the name is clear enough, but what are the limitations of the standard package?

• End-user docs should not be duplicative. The package description information and almost everything about a package for administrators and developers is already described in the package itself through two basic development document templates: a Requirements Template and Detailed Design Document.