<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
<meta name=Generator content="Microsoft Word 11 (filtered medium)">
<style>
<!--
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman";}
a:link, span.MsoHyperlink
{color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{color:purple;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-compose;
font-family:Arial;
color:windowtext;}
@page Section1
{size:8.5in 11.0in;
margin:1.0in 1.25in 1.0in 1.25in;}
div.Section1
{page:Section1;}
-->
</style>
</head>
<body lang=EN-US link=blue vlink=purple>
<div class=Section1>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>[This is a new thread to allow us to discuss documentation
formats separately from documentation requests.]<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>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 <i><span style='font-style:italic'>organization</span></i> of the
documentation. That leads to the biggest con: the documentation must be <i><span
style='font-style:italic'>organized</span></i>. 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.)<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>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.<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>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.<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>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.<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>Just some of my thoughts. Please ruminate and respond!<o:p></o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'><o:p> </o:p></span></font></p>
<p class=MsoNormal><font size=2 face=Arial><span style='font-size:10.0pt;
font-family:Arial'>-MC<o:p></o:p></span></font></p>
</div>
</body>
</html>