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

[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.

It's something we can change at any time, though.  It seems like a good idea right now, but it's one of those things that I may severely regret in 5 years.  Does anyone else have an opinion on this matter?

> >
> > Now that the wiki has been made available, I would like to strip
> > most of
> > the documentation from the doc/ directory in favor of the wiki. It
> > does
> > not make sense to have the documentation in more than one place. The
> > wiki supports exporting the documentation as a PDF, so we can still
> > include the docs in a tarball.
> 
> I like if the documentation stays with the code. This is luckily the
> case with the most important docs (inline XML, configs/*.conf.sample).
> If docs/ is moved to the wiki I don't mind. Just make sure to export
> the documentation also to .txt files as I usually have only text-based
> servers.

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?  :-)

--
Russell Bryant
Digium, Inc.  |  Engineering Manager, Open Source Software
445 Jan Davis Drive NW   -    Huntsville, AL 35806  -  USA
jabber: rbryant at digium.com    -=-    skype: russell-bryant
www.digium.com -=- www.asterisk.org -=- blogs.asterisk.org