[asterisk-dev] Command Syntax -- weird?

[Peter Beckman]

On Sun, 23 Apr 2006, Tzafrir Cohen wrote:

>>  What I'm hoping is that the work I'm doing with the Asterisk user
>>  documentation is that the developers can focus on writing the code and
>>  making it work, and the people in charge of documentation can get a
>>  "Change Log" from the developers on the changes, and the doc folk can
>>  either look at the code, or look at the Doxygen documentation, and turn it
>>  into valuable, end-user documentation.
>>
>>  I have no interest in putting documentation into code.  I do, however,
>>  think that the "show application Dial" documentation can be confusing due
>>  to the lack of consistency between functions.  Having documentation online
>>  that is in-step with the Asterisk code is vital, IMO.
>
> Can you suggest an improvement? Consider that any change in the syntax
> can break existing dialplans of people, and thus has to be done
> carefully.

  I think Steve Murphy is in a better position to make code changes that
  will affect config files, dialplans, etc.  I've emailed with him and he
  has a better handle on how Asterisk works, and how best to pursue more
  consistent external application specifications.

  Change always breaks things.  The question is when does breaking things
  now make things better in the future?  Sure, changing around a few strange
  function syntaxes won't make much of a difference.  But I do think that
  consistency is worth breaking backward compatibility for.

> The framework you put looks useful. However I fear that if the base
> won't get updated from the code, it will get "rotten".

  I think that Asterisk developers should focus on code and rough
  documentation, which would be picked up by the Docs group.  The Doc group
  then reviews it and turns it into documentation that includes examples,
  use-cases, caveats and a more in-depth analysis of the code.

  I'm trying to stir up interest in the Asterisk-Docs group to organize a
  group of dedicated people who can commit to keeping the documentation for
  Asterisk up to date, in lock-step with the development release calendar.
  The docs should be updated and ready for release at the same time the next
  version of Asterisk is released.  If that can't happen, you are right --
  the docs get rotten, and nobody will use them.

  What docs do currently exist are difficult to decipher, due to the lack of
  a "single voice" -- guidelines that make all documentation consistent
  between function, language and inner-working definitions, and that include
  examples, use-cases, caveats, version changes and the like.

Beckman
---------------------------------------------------------------------------
Peter Beckman                                                  Internet Guy
beckman at purplecow.com                             http://www.purplecow.com/
---------------------------------------------------------------------------