[sword-devel] Project Update - Documentation

[Derek Neighbors]

I would strongly recommend DOCBOOK for documentation.  It allows you to
create once in SGML then port instantly to all other formats.  XML, HTML,
RTF... So you write once and can offer in a variety of formats very easily.

Plus its free and and even has free books from OReilly.  It is worth looking
into.

Derek Neighbors
DFC, Inc.
http://developers.forchrist.com
dneighbors@forchrist.com

> -----Original Message-----
> From: owner-sword-devel@crosswire.org
> [mailto:owner-sword-devel@crosswire.org]On Behalf Of Daniel Glassey
> Sent: Saturday, January 08, 2000 5:31 AM
> To: sword-devel@crosswire.org
> Subject: Re: [sword-devel] Project update
>
>
> On 7 Jan 00, at 19:08, Troy A. Griffitts sent forth the message:
>
> > So many people have actually been contributing tangible pieces to the
> > project that I have been overwhelmed by the task of administration.
> > For some time now I've been trying to learn the art of 'delegation'.
> > I suppose I like to have my hands in everything 'to make sure it is
> > done right' :)
>
> I know the feeling :)
>
> > Well, I've been doing a really _poor_ job working on
> > _lots_ of things, and I would like this to change.  My apologies for:
> > work submitted, but not integrated, unanswered emails, commitments to
> > features never implemented, CDs not sent, API help not given, API
> > documentation deficiencies, and the list goes on.
>
> For the work submitted but not integrated it would probably be
> worth giving people working on stuff commit access to the CVS so
> that you aren't the main focus point there. That way it could just be
> added. People would need to be responsible though and communicate
> well or it will get messed up.
> If you like I could do the CVS setup of modules, users and stuff.
>
> The API documentation basically needs anyone (that's other people
> as well as you Troy) who has used it to add in comments where
> appropriate. We ought to decide on a documentation producer like
> Doc++, KDoc etc that can produce html from the comments in the
> code, and then move the comments that are there around to get the
> docs done.
>
> With the CD's, are there other people that can distribute them?
>
> If mailing list archives got set up on the site (especially support) then
> you could dump all mails with todo stuff into, so that anyone that can
> can deal with them. I guess an open source _community_ is for
> dealing with this kind of stuff together.
>
> > I would love to get back to work, but am constantly feeling negligent
> > and discouraged because of obligations unmet.  What used to be fun is
> > slowly becoming a 'must do'-- a 'job'.
>
> It sounds like you need to offload a lot of the admin and support
> stuff. I guess they can be the most time consuming and
> boring/frustrating but neccessary.
> It would probably be worth deciding which bits you really want to
> do and which bits are getting you down in particular and asking for
> help in the latter.
>
> I vaguely remember someone offering services for project
> management earlyish last year. Are they still around and can they
> help with this?
>
> > I've been thinking about how to resolve this, but don't have any novel
> > insights.  My best guess is that we need to have a better
> > infrastructure in place to facilitate each of you to contribute in the
> > ways you wish.
>
> I hope the ideas above help a little, even if not that novel.
>
> > Having said this, I see many of these items with different priorities
> > than I would have seen them a week ago.
>
> > PS.  Didn't anyone else think it was cool that Bjarne Stroustrup wrote
> > us regarding our work on a non-proprietary property mechanism?!
>
> Yep :)
>
> Regards,
> Daniel
>