[sakai2-tcc] TCC List - Request for official policy related to maintenance of documentation for each tool in Sakai

[Berg, Alan]

Hi,

My 5 cents. A help documentation sweep per release similar to other sweeps makes sense. The alpha / beta boundary would make a good fixed point in time.  A tester(s) could follow through the help as if it was a test plan and Jira any points that are confusing.

Over process: We have custom scripts, some magic and heroic work of individuals such as Stephen Marquard. We have also the potential to upgrade the help tool to something similar to the Knowledge base tool of EDIA. I also believe, but please correct me if I am wrong, that we have only one current version of help. I would suggest for bonus points:

1) Review the current help process, especially the scripting process and revision control  - Stephen what is your view?
2) Review the current help tool and compare with the Knowledge base tool from EDIA - Roland (from EDIA) can you explain to the TCC what the potential of the tool is?
3) Decide if we actually have resources to improve the process

Alan

Alan Berg
QA Director - The Sakai Foundation

Senior Developer / Quality Assurance
Group Education and Research Services
Central Computer Services
University of Amsterdam
________________________________
From: sakai2-tcc-bounces at collab.sakaiproject.org [sakai2-tcc-bounces at collab.sakaiproject.org] on behalf of Regan, Alan [Alan.Regan at pepperdine.edu]
Sent: 19 March 2011 00:30
To: sakai2-tcc at collab.sakaiproject.org
Cc: Robin Hill (hill at uwyo.edu)
Subject: [sakai2-tcc] TCC List - Request for official policy related to maintenance of documentation for each tool in Sakai

Dear TCC,

On behalf of Robin Hill, Mathieu Plourde, and the documentation review effort, I submit the following for your consideration.

*******

As the Executive Director, Ian Dolphin, calls for a restructuring of QA roles, the informal Help-Files and Documentation group asks that more rigorous attention be devoted to our common documentation system, the Knowledge Base (KB).  Although Indiana maintains it conscientiously, the quality of the KB depends on the materials supplied to Indiana.  The inconsistent quality of that submitted content frustrates many users.

The KB files of several tools reflect shortcomings of inaccuracy, incompleteness, and inconsistency; for some, the developer institutions lack the manpower to work on the files, and for others, there is no apparent responsible party at all.  Other types of useful documentation such as how-to expositions and pedagogical case studies, sought by many potential adopters, are not provided in any coherent way.

These issues undercut the appeal of the product, the reputation of the community, and the credibility of open-source software in general.

There is no quick and easy way to resolve these issues, as shown by the history of broad documentation efforts which have fizzled out.  Our willingness to review and revise the Sakai 2.8 Help files piecemeal will not, by itself, put Sakai documentation on a firm footing.

To address this issue, we submit a two-part proposal.  First, we ask that all tools require a sponsor and a plan to maintain both the code and the documentation, including end-user help files.  The documentation maintenance plan can take many forms.  It may be that the developer institution takes full responsibility for maintaining the help files, such as the great work by Stanford with Tests & Quizzes.  Or perhaps it's a partnership between the developer and other institutions that use and value the tool.  In the end, for a tool to be available, it must have a current sponsor and an up-to-date plan that will produce quality code and documentation.

Second, we would also like to see the documentation undergo the same rigorous QA process as the code. Just as Sakai partners and collaborators contribute to the "test fest" for each tool, we ask that testing extend to the help files as well.  Admittedly, this would create an additional burden, but the time and effort spent will benefit the end-users of every institution that uses Sakai.

We feel that requirements like this may not be taken seriously unless they are sponsored by the TCC (for 2.x) and the Managed Project (for OAE), along with the Foundation itself.  We ask for your help to formulate an official policy on this topic, supported and managed for the long run.

Thank you for your time and consideration.

Sincerely,
Robin, Mathieu, Alan

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai2-tcc/attachments/20110319/ef5fa2ad/attachment.html