[asterisk-dev] doc/ -> wiki.asterisk.org

[Klaus Darilion]

Am 02.11.2010 17:09, schrieb Russell Bryant:
>
>
> ----- Original Message -----
>> Am 01.11.2010 19:52, schrieb Russell Bryant:
>>> Greetings,
>>>
>>> As you have probably seen by now, there is a new project wiki
>>> available:
>>>
>>>       http://wiki.asterisk.org
>>>
>>> This wiki was originally created to host documentation for the
>>> Asterisk
>>> SCF project. We then realized that it would be very valuable to host
>>> all of our Asterisk documentation there, as well. At this point,
>>> everything from the doc/ directory (from Asterisk 1.8) has been
>>> imported
>>> into the wiki. In addition, we have created a tool that syncs the
>>> XML
>>> based documentation from the Asterisk source with the wiki
>>> (applications, functions, AMI actions, AGI commands).
>>
>> I really miss a version thing on the Wiki. There will be new versions
>> of Asterisk and documentation is worthless if it does not specify the
>> version. This is one of the biggest problems with the voip-info wiki
>> as you never for what specific Asterisk version the documentation is. So,
>> IMO the Asterisk documentation must be moved into subchapters per
>> release. There may also be a Trunk documentation.
>>
>> It should be similar to what we have on Kamailio website (or other
>> projects), with clear differentiations for every release, e.g.:
>> http://www.kamailio.org/w/documentation/
>> http://httpd.apache.org/docs/
>> http://www.postgresql.org/docs/
>
> My thinking was that we could mark documentation with the version that it applies to.  "This feature was first introduced in Asterisk 1.8", for example.  I guess the biggest benefit of this route is keeping all of the comments.  I expect that once everyone is able to leave comments on the documentation, they will really start to add value.  If documentation is duplicated for each version, the comments will be fragmented.

Yes, comments will be fragmented. But on the other hand, it may be that 
comments are not valid anymore as behavior of an application was 
changed/fixed or a commented workaround is not needed anymore. Take a 
look at voip-info wiki: there are lot if comments that "this does not 
work, you have to use workaround xyz".

Maybe it would be possible to add links to the comments to older 
Asterisk versions at the bottom of the page to refer readers to old 
comments.

Also, when the behavior of an application is changed then you always 
would need to describe the old behaviors too - this may confuse people.

Finally this means the inline XML documentation needs to have this 
versioning (as it is the source of the wiki), e.g. similar to following 
(see added/obsolete/removed parameters):

   <function name="SIPPEER" language="en_US" added="1.2" obsolete="1.12" 
removed="1.14">
     <synopsis>
       Gets SIP peer information.
     </synopsis>
     <syntax>
       <parameter name="peername" required="true" />
       <parameter name="item">
         <enumlist>
           <enum name="ip" added="1.2" changed="1.8">
             <para version="1.2">(default) The ip address.</para>
             <para version="1.4">(default) The IPv4 address.</para>
           </enum>
           <enum name="port" added="1.4">
             <para>The port number.</para>
           </enum>
           <enum name="mailbox" added="1.2" obsolete="1.10" removed="1.12">
             <para>The configured mailbox.</para>
           </enum>

Probably there will be situations where it is not easy to describe 
changes in the XML data. If I look up the description of SIPPEER I am 
not interested in when a feature was introduced or which parameters were 
in 1.0 release but were removed. If I really need this info I just 
change the URI to point to the documentation of an older release and 
compare it. And for new feature I prefer the CHANGES file.

Asterisk is not that stable - there are always a lot of new funcs/apps 
and new parameters to those. I think this will really fast make the 
reading of the documentation complicated.

Thus I vote for a clear distinction between the versions and keep a 
dedicated documentation for each version. Especially with LTS versions 
it will happen that people look up documentation of older releases and 
are not interested in documentation and comments of a newer versions.

> I know we can export into PDF, but I'm not sure about plain text.  I'll have to look into it some more.  Besides, you always have text-mode web browsers, right?  :-)

*lol*

Yeah, sure. Except you configure Asterisk on a carrier server with port 
80 blocked and RHEL4 with decent packet manager to install lynx. :-)

regards
Klaus