[Freeswitch-users] Documentation Formats

[Michael Collins]

[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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.freeswitch.org/pipermail/freeswitch-users/attachments/20070923/27f1207b/attachment-0002.html