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

[Paul Belanger]

On Tue, Nov 2, 2010 at 3:48 PM, Klaus Darilion
<klaus.mailinglists at pernau.at> wrote:
> 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".
>
I'm divided on the issue. I do like the idea of users providing
feedback to a wiki page (if they are not able to directly edit it)
however, Klaus's point about comments becoming out-dated or turning
into support questions is valid.  Perhaps we can look to another
project's solution?

> 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>
>
Personally, I like this idea.  Not only does it span all version of
Asterisk, it provides detailed information about functionality
changes.  A great tool helping users migrate between Asterisk
versions.  I would be willing to help implement something like this.

> 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.
>
+1 Well said.

-- 
Paul Belanger | dCAP
Polybeacon | Consultant
Jabber: paul.belanger at polybeacon.com | IRC: pabelanger (Freenode) |
Blog: http://blog.polybeacon.com | Twitter: http://twitter.com/pabelanger