Table of Contents
Abstract
Generguide allows you to selectively merge documentation from around the web into one target document. This is particularly useful for generic business processes. We hope that generguide will be widely used to develop an integrated network of business processes.
Generguide builds upon Docbook, xinclude, XSLT, and related technologies.
Generguide contains Generic Documents which can be used without modification, or serve as templates for custom Project Documents. The first generic document is a Software Developers' Guide which describe processes and tools for the full software development life cycle.
Generguide extends the concept of Modular Docbook to allow users to selectively include modules based on a local configuration file.
The components of Generguide are categorized as follows:
- Build Tools
A collection of Scripts, XSL Stylesheets and XML Processing applications implemented to work according to the Generguide project structure.
- Conventions
Defined procedures and methods for creating, editing and outputting Project Documents is a manner that is uniform and consistent.
- Boiler Plate Documents
Generic Documents that can be used as is, without modification, or can serve as templates or starting points for the creation of custom Project Documents.
Check out the Generguide Configuration Builder for a dynamic example of generguide.
Modular Docbook means your source documentation is broken up into smaller files that are recombined for publication. The advantages of modular documentation include:
Reusable content units.
Smaller file units to load into an editing program.
Distributed authoring.
Finer grain version control.
To build modular documentation, use <xinclude> tags in your master document to reference module files. Refer to Docbook XSL: The Complete Guide for a comprehensive explanation of how this is done.
The Generguide Configuration file is used over-ride Modular Document <xinclude> references and force module files to be imported from another location, or not be imported at all.
Example 1. Configuration File
<generconfig>
<nodeset href="http://genericdevelopersguide.org/guide/master.xml">
<node id="intro" href="/home/generguide/guide/intro.xml"/>
<node id="code" href="http://gnucodingstandards.org/generguide/code.xml/>
<node id="refactor" filter="EXCLUDE"/>
</nodeset>
<varset>
<var name="projectname" value="My Project"/>
</varset>
</generconfig>Generguide is ideal for tailoring Generic Documents. Using a local configuration file, you can:
Specify sections to exclude.
Replace sections with local sections or sections from elsewhere on the web. Note that included sections can also contain <xinclude> tags which can be over-ridden by the configuration file.
Specify documentation variable names, like project_name or project_home_page.
Generguide tools build upon Docbook XML, xinclude, XSLT, and related technologies.
For version 0.2 of generguide, source documentation is stored in Simple Docbook. We have plans to support other document types in future.
Target documentation includes all documentation types supported by Docbook XSLT, including: html, xhtml, pdf, text, etc.
The generic guide provides software development processes for open source projects. It cover processes, conventions and recommended tools. We hope this guide will become a de-facto standard for open source projects.
Table 1. Sample Software Developer Guides
| Generguide Configuration Builder | Build your own Guide using the generguide CGI interface. |
| Generic Software Developers' Guide | The generic text. |
| Geotools Software Developers' Guide | The original guide grew out of Geotools2 |
The Guide is written in a modular fashion so different projects can easily overwrite, add or delete sections.
Our aim is to only recommend open source tools, however in some cases we have recommended tools which are semi-free, free for open source projects. Where applicable, widely accepted conventions and open standards are used. It has been satisfying to discover the breadth of quality open source tools which support software development. It is hoped that this document will highlight areas where tools can be improved or developed and encourage developers to focus on these areas.
The guide is already quite comprehensive, it grew out of the Geotools Software Developers Guide and has sections copied from all the best practises we could find on the web. However there is still plenty of improvements to made:
Review by tech writers (we are all coders).
Fill some of the holes we still have.
Develop processes for languages other than Java.
Develop processes for different development methodologies (Extreme Programming, Mil Std Processes, etc).
If you think you can add to or improve these sections then we'd be delighted to hear from you.
We'd like to see Generguide help as many people as possible. To this end, we feel all documentation should be covered by the GNU Free Documentation License and tools covered by GNU General Public License.
Copyright (c) 2003 Cameron Shorter. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being with no Invariant Sections, with the Front-Cover Texts being no Front-Cover Texts, and with the Back-Cover Texts being no Back-Cover Texts.
Copyright (c) 2003 Cameron Shorter. Permission is granted to copy, distribute and/or modify Generguide code under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.