Project Documentation Site
Project Documentation Site
A project documentation site is oriented to project developers, and their managers, though the users or customers involved in the project's development might also find material of interest on the site.
Both the components of a project site, and the tools by which it is maintained, are critical to its utility.
Project Site Components
A project's documentation site should include:
- A project overview, summarizing both the functional usage of the project and its implementation framework
- A brief overview of site contents
- A listing of client applications (if known and applicable)
- HowTo documents for developers new to the project (e.g., describing toolsets, dependencies, and configurations)
- Documentation of project standards (coding, documentation, testing, version control, etc.)
- Documents describing strategic goals, roadmaps, specifications, and partnerships
- A revision / release history, if applicable
- API documentation (i.e., javadoc)
- Documentation of XSLT, schemas, and other project components
- Documentation of deployment descriptors
Project Site Implementation Technology
The Streek Project site is implemented using Apache's Forrest. Itself built on the Apache's XML publishing framework Cocoon, Forrest allows creation of source material in its own document, DocBook, HTML, and other formats. Using XSL and CSS that a user is free to modify, the Forrest engine generates a tree of skinned HTML and PDF files suitable for publishing.
Many sites began to utilize Forrest well in advance of its v. 1.0 release.
Streek's project site uses a modestly extended varient of Forrest's DTDs, and a slightly modified varient of the skin called "avalon-tigris." XML Schemas are documented using the xs3p stylesheet developed by Australia's Distributed Technology Research Centre. Javadoc is copied into the Forrest-generated site tree after the Forrest build files are run. Ant targets to build the Streek site are invoked from the project's root-level build.xml file.