[Freeswitch-users] Documentation Formats

[Michael Jerris]

If it is the "right" thing for freeswitch or not matters little if no one is
willing to take this on and volunteer to organize and maintain it.  Without
someone offering, it's idle chatter to discuss it.  So, I'll offer it up
now, is anyone interested in taking on this project?

Mike

On 9/24/07, Michael Collins <mcollins at fcnetwork.com> wrote:
>
>  [This is a new thread to allow us to discuss documentation formats
> separately from documentation requests.]
>
>
>
> The question of why to use Docbook was brought up by Trixter.  I've been
> researching Docbook and I can see definitely pros along with the cons.  The
> biggest pro would be the fact that Docbook requires *organization* of the
> documentation.  That leads to the biggest con: the documentation must be *
> organized*.  That will take a lot of work, but the rewards are huge.
>  Docbook requires lots of metadata for the document(s) in question.  (It's
> essentially just XML, but it's well-defined XML, structured specifically for
> the benefit of technical documentation projects.)
>
>
>
> Brian is correct: this is a huge project within the FreeSWITCH project.
>  It probably needs a champion, or at least a person or persons in charge.  I
> would recommend that whoever is in charge know enough about FS to guide the
> documentation.  He or she needn't be a FS expert, but definitely needs to be
> familiar with the whole scope of the FS project.
>
>
>
> For the record, I suck at that kind of management, otherwise I'd
> volunteer.  However, I am pretty good at proof-reading and editing existing
> documents.  I am available to start helping to convert existing
> documentation into Docbook format, assuming the FS project leaders would
> like to take the documentation in that direction.
>
>
>
> Before we do anything else, I'd like anthm, bw, and Trixter to give this
> question some serious thought: is Docbook right for FS documentation?
>  Please don't answer the question today.  Give it some thought.  Sleep on
> it, kick it around, discuss it amongst yourselves and then let us know what
> you think.  One last comment: Docbook isn't meant to replace the wiki, but
> rather to complement it.  The wiki is still a vital tool for the community.
> The Docbook would be more like "official" documentation, e.g. perhaps it
> would require Anthony's or Brian's seal of approval before it is "official,"
> while the wiki remains the community-owned bulletin board.
>
>
>
> Just some of my thoughts.  Please ruminate and respond!
>
>
>
> -MC
>
> _______________________________________________
> Freeswitch-users mailing list
> Freeswitch-users at lists.freeswitch.org
> http://lists.freeswitch.org/mailman/listinfo/freeswitch-users
> UNSUBSCRIBE:http://lists.freeswitch.org/mailman/options/freeswitch-users
> http://www.freeswitch.org
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freeswitch.org/pipermail/freeswitch-users/attachments/20070924/63fe4f59/attachment.html