[asterisk-doc] Application Documentation

[Leif Madsen]

On 5/3/06, Russell Bryant <russell at digium.com> wrote:
> Leif Madsen wrote:
> > Very cool! What might we do about being able to keep all of this
> > documentation synchronized between the documentation project, and
> > Asterisk itself? It might be pretty useful to have a website where
> > people can read about the various applications and functions, and for
> > that documentation to be in sync with what is show when you do a show
> > application <foo>.
>
> I'd like to reiterate the ideas that Mark presented on the conference
> call when we were discussion this a couple weeks ago.  The idea was to
> track which SVN revision number the documentation is up to date with.
> Of course, having the documentation crew look at every single commit to
> see if it affects documentation doesn't sound all that appealing.
>
> However, one thing we could probably do is make a policy to put some
> kind of tag in the commit messages that indicates that the commit
> affects documentation.  Then, we could have a post-commit script that
> looks for this tag, and sends the commit to the documentation mailing
> list when appropriate.

Thanks Russell -- that happened to be the one conference call I was
unable to make.

I guess what I'm thinking is that we somehow centralize the
documentation so that if something gets modified in the main Asterisk
branch, it'll automatically update the documentation project, and
vice-versa. That way, when we "fix" or clarify some sort of
documentation in the project, it will automatically keep the Asterisk
branch updated with the new documentation. At the very least, I'd like
to see it somehow mark that documentation has been updated and needs
to be reviewed. That way, we're keeping things consistant and not
needing to backport documentation changes between the two projects
that essencially have the same goals.

> > It logically seems to make the most sense to use
> > DocBook in Asterisk to keep all the documentation centralized
> > (end-user documentation of course -- coding documentation is in
> > doxygen).
>
> I'm not sure if this is the direction we should take.  However, the real
> issue is that the information about the arguments to an application is
> not stored in any way that code can automatically figure out what to do
> with them.
>
> Essentially, there is a big blob of text that describes all of the
> options, which is what you see when you do "show application whatever".
>  Then, the code itself in every application manually parses the string
> of arguments.  These two things need to be somewhat unified so that the
> arguments can be parsed before they make it to the application.  When we
> get this cleaned up, the ability to generate documentation at the level
> of refinement that we need for this should be solved as a side benefit.

I'd agree with that. Whether its DocBook or some other method, it
would be nice to be able to keep the changes merged together so that
when one or the other project updates some text, both projects receive
the update. I realize there might need to be some sort of flag that
goes to the Asterisk project to say, "Hey, the docs project updated
something -- verify this is true!" -- but I'd assume anything that
goes into Asterisk documentation directly can safely flow down to the
docs project (maybe we want the flag thing to go the other way to so
there is more eyes looking at the docs and verifying?).

> > Suggestions? I think this would be a good topic to put on the
> > conference call for next week.
>
> We discussed some of these issues during the first conference call and
> agreed that it was something we would revisit after 1.4 is released.
> I'd rather reserve the time in the conference calls for things that need
> to happen before 1.4 released for now.

Understood. I had forgotten there was discussion of documentation in
the conference call that I missed.

Leif Madsen.