[Asterisk-doc] Is the project dead?

[Leif Madsen]

On 4/23/06, Peter Beckman <beckman at purplecow.com> wrote:
> > How can we start making the contributions?
>
>   I fixed the strange issue with the docs mentioned above.
>
>   Right now the docs sit on my home server.  I think Jared was going to set
>   up an SVN area I could put the code in and allow people to check it out
>   and contribute.
>
>   There are a few things that I believe need to happen though:
>
>      1. Asterisk Docs member buy-in.  I'm not familiar with who
>         heads/runs/manages the AsteriskDocs.org project and website.  I
>         don't want to step on toes pushing a new way to document onto a
>         bunch of people who have clearly put in many hours of work into this
>         project already.  If the Ast-doc folk like what they see, great.
>         I'd love to see everyone on the team get excited about this and
>         throw their support behind it.

I guess technically that would be Jared Smith, Jim van Meggelen and
myself. I'm excited, but the reason for the lack of documentation
lately is that we're all extremely busy and haven't had any "new
blood" in quite some time. While Asterisk is growing in terms of the
number of people using it, I have yet to see any significant number of
people able and willing to contribute documentation -- its been this
way for over 2 years unfortunately.

>      2. Document the process.  We could just put this in SVN and see what
>         happens, but just letting everyone go to town making documentation
>         is an easy way for things to get messy very quickly.  There needs to
>         be a process to allow people be commiters, a review process for each
>         commit, some guidelines that documentation writers need to
>         follow, and an automated way to enforce as many of those guidelines
>         as possible, to reduce the amount of effort "supermods" need to put
>         forth to get good documentation to the people.

I'd rather keep the number of people who have access to the SVN
repository to a small and controlled group or else we're going to have
all sorts of problems. Documentation needs some very special attention
such as editing and verification (as much as is practical).

The #asterisk-doc channel on IRC is a really good place to discuss
things -- I don't get a chance to look at the mailing list every
single day, but I'm usually on IRC for good portions of the day -- at
least checking in and bugging Jared with my questions :)

>      3. Commitment to constant review.  Documentation is only as good as its
>         editors.  If the docs contain inaccurate, misspelled and just plain
>         wrong information, then all that work will be in vein.  People need
>         to commit to reviewing documentation bug submissions and making
>         updates quickly and accurately.  A small team needs to interface
>         constantly with the development team to make sure that documentation
>         for 1.2.8 is ready and available when the dev team releases 1.2.8,
>         not 2 months later.

Very difficult to do -- when we were writing the starfish book, we
were trying to keep up with the developers in order to try and be as
accurate as possible when 1.2 was finally released -- let me tell you,
that was QUITE some work, and many pages (and even a chapter) needed
to be totally re-written. However, saying that, with the new release
cycle, it should be a lot easier to keep up to date, and not so many
fundamental changes are going to happen between releases -- such as
they did between 1.0 and 1.2.

>   We can take a lot of these things from the PHP Documentation Group.  They
>   have guidelines, scripts, and have documented fairly well the process to
>   documentation.  By riding on the coattails of their successful framework,
>   the Asterisk Documentation can continue to grow and flourish as Asterisk
>   matures even futher.

This is what I'm hoping to -- however, I'm not in the position to take
on yet another project. I'd like to be more of someone to look to for
guidance as I've been playing this game for quite a while now, but
fresh blood is needed who can perform some of the grunt work -- I'm
ready to move on to polishing :)

>   I am but one person; for this to work there needs to be a small and
>   dedicated group of people willing to back eachother up, help enforce some
>   guidelines and rules, and keep things moving.  I'm in, but I can't do it
>   alone.

Exactly -- hence why we need more people to participate. I'm hoping
the new framework you are coming up with will make it easier to allow
contributions from many people, and for each of them to not require
such a huge dedication of time to writing full chapters -- but able to
focus on some very specific part of Asterisk and document the heck
outta it. This seems to be how Asterisk works in many circles -- a
keen focus on a particular area, with little or no knowledge about
other areas.

Peter, thanks for taking on this new project -- please let me know if
I can be of any assistance -- I recommend you get on IRC and just idle
and ask questions as you come across them. In fact, that goes for
anyone interested in documentation.

Thanks!
Leif Madsen.