Re: [Pas-dev] Notes on a 1.0 release

[Kyle R . B. <mo...@vo...>]

> As soon as I scrape off the bitter, I'll help. How do you wanna do this?
> Outline what needs done, or just have at it?

I'd like to look at using DocBook [http://www.docbook.org], as that will
allow us to target txt, html, ps, and pdf all at once.

I'd like to appraoch this a few ways.  First, by finishing all of the
interals documentation (the in-line POD API documentation).

Then trying to come up with a table of contents for three major user
style manuals.  I think a good approach would be to write an Administrator's 
Guide (installation, configuration, on-going maintenence, external software
dependencies, system issues, etc), a Developers's Guide (users guid - how the
software is organized, a walk-through of how to develop PSP pages and Page
objects [request handlers], a chaper on 'best practices', how to redirect,
how to forward a request [and so on], a module reference [the api docs]), 
and an Internals Developers's Guide (the people on this list - code 
organizaion, minimum coding/documentation standards, etc.).


How does that sound?  Your idea of developing an outline is probably a good
one.  I'm up for doing that on the mailing list (which will help get
input from multiple people, as well as be an archive of what we come up 
with).


So, shall we comment on the 3 major user manuals as described above?
Is that a good place to start?  Does the description of their coverage
sound appropriate?

If we [most of us] agree on those 3 major manuals as a starting point,
then the next issue will be the TOCs for them.

I think we should probably start with the Admin guide, and the Developer's
guide, as those will probably be the most used.  The internals developer
guide will probably be just fine as the POD api documentation.


What say ye?

Kyle


-- 

------------------------------------------------------------------------------
Wisdom and Compassion are inseparable.
        -- Christmas Humphreys
mo...@vo...                            http://www.voicenet.com/~mortis
------------------------------------------------------------------------------