Child pages
  • Documentation Standards
Skip to end of metadata
Go to start of metadata

The Need for Documentation

Documentation for an open source project is a fundamental community need. It paves the way for both new users and contributors to join the community, and is an essential communication for distributing technical expertise.

Documentation Format (working principles for Release Docs)

nothing more than Clay's private opinions right now - some working principles

  • Documentation source should be in an open format which may be readily published in a variety of other formats - HTML, Plain Text, PDF, etc.
  • It should separate structure and semantics from presentation as much as possible.
  • It should be easy for developers to write, or volunteers to contribute, without a significant learning curve.
  • There should be some mechanism or venue for ongoing review and comment (i.e. this wiki) without introducing a significant maintenance burden.

For these reasons neither HTML, Wiki markup, nor Microsoft Office are very suitable. The DocBook project, which provides a mature DTD and XSL stylesheets for conversion to HTML, and which is supported in numerous other editor tools (including Microsoft Office and some Eclipse plugins), is the leading contender for now. It is, however, more complex than is needed, and some XSLT work may be required. So it is not yet the ideal solution, but seems to be the best option.

Proper use of this Confluence Space

The danger this space must take into account is the potential confusion that may be caused over having documentation available both here and in other locations. This space is an attempt to harness the advantages of having a place for easy review and comment without muddying the waters. Some guidelines are required:

  • If any of these pages duplicate content provided elsewhere (e.g. docs/architecture) they should, as a general rule, hold the identical content. This will be a maintenance cost, but it purchases the refinements that come from a more ready peer review.
  • When any of these pages goes out of synch with documentation labeled elsewhere (e.g. when pages are in a state of active editing or revision) they must clearly be identified as such at the top of the page.
  • No labels

1 Comment

  1. There has been a discussion of documentation on the Sakai-user mailing list. Rather than repeat that conversation here, I suggest those who are working on Sakai documentation review the comments. Also, for documentation standards, I'd like to see much greater emphasis on content than the electronic medium used to prepare documentation. The standards for Unix man pages are a minimal starting point, but I think the R Project does a much better job, In particular, besides having standardized information for manual pages, the latter has a second category of documentation called "vignettes" that are somewhat like a user's manual. Still, the audience for R is quite sophisticated, consisting largely of professional statisticians, faculty members, and advanced graduate students. For something like Sakai, one needs to address such users, as well as novice users like first-year undergraduates. So at a minimum, there needs to be introductory materials like tutorials and getting started guides, reference documentation, and user guides explaining how to accomplish certain kinds of tasks. The reference documentation needs to be complete and authoritative. Currently this is not the case (e.g., where is the csv format for Schedule documented?), and much of the end-user documentation in this space is contributed in duplicate from multiple institutions, none if which is designated as "officially" responsible for the documentation. Furthermore, the organization of documentation in this space creates a needle-in-haystack situation. If, for example, one were looking for the csv documentation mentioned above, how would they know which if any of the contributed "End-User Support Documentation" has the information?