[asterisk-dev] What happened to the documentation of queue_log entries?

[Russell Bryant]

On Mon, 2010-11-15 at 15:19 +0100, Håkon Nessjøen wrote:
> On Mon, Nov 15, 2010 at 2:37 PM, Russell Bryant <russell at digium.com> wrote:
> > Committers are responsible for ensuring that the documentation be updated as appropriate for code being committed.  This is no different than it has been for a long time.
> 
> For me as a contributor, and not committer, it's harder for me to
> contribute documentation along with my patch. It won't automatically
> follow the patch at issues.*.org or reviewboard.*.org
> As far as I saw, it's not documented in the current wiki, how this is
> supposed to be done, seen from a contributors standpoint. Where am I
> supposed to add documentation for queue_log changes?
> To the ticket note itself?

You're right that it's a bit more difficult.  However, I'm making the
gamble here that the benefits we gain from the wiki for the user
community outweigh the minor inconveniences we may take on in the
development community.  On the developer side, even though it's not in
svn, I find editing in the wiki _much_ easier than the previous format
we had the documentation in.  It's much easier to focus on content.

As for contributions that affect documentation, you are correct that
there is not yet a documented process for that.  I will get that done as
soon as I can and post back to this list.  However, in short I would
expect that documentation just be submitted as plain text and it can be
imported into the wiki at the same time as committing the code.

The reality is that very few people actually contribute any significant
amount (or really at all) to the documentation.  For those who put any
significant effort into the documentation, they can have direct wiki
access.  I also think we have a much better chance of growing the pool
of people that contribute to documentation with this system than LaTeX
in svn, which is where we were before.

So, in summary, yeah, you're all right.  It's a bit less convenient in
some situations.  I think the end result is far better for the
community, overall.  I hope you see that, too.

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