[Firebird-docs] Re: [Firebird-admin] Documentation

[Mark O'D. <mar...@lu...>]

Hi Helen

All sounds pretty good stuff, and it's sounds like some sort of solution 
to our documentation conundrum. 

I think the linux documentation uses the SGML suite of tools.  I looked 
at it a but, but not much.  They generate html, ps, txt versions from 
the source.

Bill would be good to get involved, I understand he had a lot of his own 
stuff anyway that could help.

On the sourceforge stuff, they seem to be over their initial growth 
pains, and are a bit more reliable recently.  Depending upon how you go 
it might be worth useing, CVS is pretty good at distributed development, 
and that seems to be how this is also going to work.

Cheers

Mark


Helen Borrie wrote:

> Hi All,
> 
> Recently, folk have started rumbling about documentation, which is 
> GOOD.  Bear with me while I brainstorm a little here...
> 
> 1.  A radical plan which is formulating in the green, greasy depths of 
> my mind is to give up on the IBDH project - not because it aint great 
> (we REALLY need that book) but because it's financially out of reach 
> for me to do it as planned.  However, for a developer book, its 
> outline is good - the result of many eyes and hands.  I have more 
> stuff to add to the outline - ideas continue to come through - so that 
> I think we have the bases pretty well covered already through 
> community effort.
> 
> With the permission of my translators (who are a good and rational 
> bunch, for sure) I would like to transmogrify the IBDH project into 
> the Firebird Documentation project.
> 
> A bonus in this might be that I/we can persuade Bill Karwin to come 
> aboard such a project, now that the angst has subsided.  Bill himself 
> outlined an ambitious Open Document project for documenting IB, from 
> all angles.  I would be willing to take on the role of manager/editor, 
> much as I planned for the IBDH.  It would be so much the better for 
> Bill's participation.
> 
> 2.  At the time the IBDH was conceived, it was in the context that ISC 
> was planning to publish the updated IB 6 manuals.  We could change the 
> content and organisation of material in Ann's publication-ready 
> version radically to circumvent copyright restrictions.  The rewriting 
> and re-editing of the content would be well within my range.  There is 
> no copyright on the intellectual content of these docs.  In my view, 
> the IB6 Manuals' organisation is still very poor.  We could kill two 
> birds with one stone by reusing the ISC work in a revised, expanded 
> and more user-friendly documentation set.
> 
> 3.  As to format... I'm one who likes to have a well-indexed book on 
> hand in preference to anything in electronic format.  There are lots 
> who agree with me;  and just as many who prefer helpfiles, html, PDFs 
> or whatever.  The "infrastructure" of the IBDH was on track to store 
> all the content in a database and apply various processing tracks to 
> it to enable output in many formats - hard-copy drafts, print-ready 
> copy, HTML, Linux How-To, etc.  Obviously the means to this end is XML 
> and Unicode.  If we can persuade all contributors to submit material 
> in plain text Unicode, we can keep things open for alternative outputs 
> to suit whatever requirements arise.
> 
> 4.  Incorporating the sourcecode development stuff...we need to get 
> this under some form of version control, I think.  I certainly have 
> provision for it in the IBDH database structure.  If we can have a 
> server somewhere that is dedicated just to documentation, I believe we 
> can do some good management and version control that doesn't suffer 
> from the vicissitudes of Sourceforge.  They do it in the Linux 
> projects and IMO it works well.
> 
> Well, just some embryonic thoughts...
> 
> Helen
> 
> All for Open and Open for All
> InterBase Developer Initiative · http://www.interbase2000.org
> _______________________________________________________
> 
> _______________________________________________
> Firebird-admin mailing list
> Fir...@li...
> http://lists.sourceforge.net/lists/listinfo/firebird-admi
> n



-- 
Your database needs YOU!
http://firebird.sourceforge.net