User Tools

Site Tools


Sidebar

Navigator

w:page:48623864:collaborative_20reference_20documentation

Collaborative documentation

VCP maintains all its documentation in a single integrated WIKI. VarIous nodes of VCP can then refer to the relevant pieces of documentation as relevant. Thus while a given piece of documentation may have initially been written for a given project or by a given project members, it is thus available for direct reference by any project or area of VCP. Our conception of documentation is thus that it is to be prepared in modular fashion, so that generic guidelines and manuals are separated from specific adaptations geared to a specific usage. Thus the specific adaptation can be presented, and the relevant module(s) pulled in from the documentation archive.

  In addition, VCP documentation is a collaborative project designed for open ended revision and expansion by our community of content developers, technologists, and users. Thus while initially a single individual may author a given document, we welcome input from others for its revision, expansion and correction. In particular, we would like to gradually archive tips for possible usages of a given tool or system, for example, in addition to the generic guidelines. We are trying to structure documentation so that such archiving of information doesn't interfere with the utility of quick guides and clarity of organization. For example, for a given set of documentations we might want to separate a general introduction to a resource, from a manual for its use, and tips for creative applications of it. We are trying to maintain consistent principles of organization and nomenclature across documentation, but there will no doubt be irregularities as we produce, edit and revise a very large body of documentation.

  Each individual component of the documentation archive will ultimately have an editor(s) listing who is responsible for its maintenance, organization and consistency. Everyone who contributes anything to the document, large and small, are listed as contributors. Thus each document at its top lists the editor and contributors, along with an original creation date, and last revision date. Since tips and other small comments can be very hard to judge - what seems essential for one may seem trivial or ill-advised for another - VCP editors are asked to err on the side of inclusion rather than exclusion. If this becomes unweildly, they will use navigation and additional components as necessary to keep documents streamlined while still retaining access to expanded information. In the meantime, some documentation may be attributed to a single author, but we anticipate that gradually over time these too will slowly transform into collectively authored documented managed by an editor.

w/page/48623864/collaborative_20reference_20documentation.txt · Last modified: 2013/04/24 06:27 by chenriot