[generguide-devel] Generguide 0.2 - Generic Docbook Guide Builder and Software Developers' Guide

[Cameron S. <ca...@sh...>]

We are excited to announce that we have our first public release of 
http://generguide.sourceforge.net .

What is generguide?
===============
Generguide allows you to selectively merge modular docbook documentation from 
around the web based.  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.

See the following URL for a dynamic demonstration: 
http://www.gisontheweb.com:8080/~cameron/cgi-bin/processconfig.pl

Generguide is particularly useful for tailoring generic business processes. 
 80% of business processes are common across the industry.  With generguide, 
common documentation can be edited collectively and referenced over the web. 
 This means your business need only focus on the 20% of documentation 
specific to your company.

We use generguide to tailor a Generic Software Developer's Guide: 
http://generguide.sourceforge.net/developersguide/developersguide.html

Generguide builds upon Docbook XML, xinclude, XSLT, and related 
technologies.

Status of version 0.2
===============
Generguide 0.2 is fully functional.  You can see it working at:
http://www.gisontheweb.com:8080/~cameron/cgi-bin/processconfig.pl
We still consider it alpha quality and I suggest you wait until version 0.3 
before committing your business to it.
They are a few design issues which we would like help with and which may 
change the structure of our configuration files and the way we use docbook.

Goals for version 0.2
================
* Find and network with people interested in similar concepts.
* Get future users to join our email lists and help refine our use cases.
* Find Docbook and XSL Gurus who will review our design and advice us on some 
design issues.

Are you a docbook or XSL guru?
========================
We want design advice on the following issues:
1. How should we implement variables within our documentation?  Currently we 
use ENTITIES like &project_name; however entity files are not XML and hence 
hard to process.  We are considering extending the Docbook schema to add a 
<variable> tag.

2. Generguide uses modular docbook, which means a docbook file can include 
another docbook node using <xinclude href="another_section.xml">.  However, 
we have run into problems when linking from one module to another because it 
causes invalid xml.  Ie, when the main doc contains <link 
linkend="an_id_from_another_section">.  What should we do to avoid getting 
invalid XML?

Looking for a host
==============
We are looking for somewhere to host our generguide demonstration site, 
currently living at:
http://www.gisontheweb.com:8080/~cameron/cgi-bin/processconfig.pl

Contact us
========
Please let us know what you think about generguide.  We haven't talked with 
many people about generguide yet and would like to know if we are onto a good 
idea or not.
Join one of our email lists: http://sourceforge.net/mail/?group_id=83647
Or email me direct: cameron AT shorter.net

Hope to be talking with you soon.
-- 
Cameron Shorter              http://cameron.shorter.net
Open Source Developer        http://generguide.sourceforge.net
                             http://mapbuilder.sourceforge.net
                             http://geotools.org
Senior Software Engineer     http://www.adi-limited.com