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@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@lists.freeswitch.org
http://lists.freeswitch.org/mailman/listinfo/freeswitch-users
UNSUBSCRIBE: http://lists.freeswitch.org/mailman/options/freeswitch-users
http://www.freeswitch.org