[asterisk-doc] Who's Willing to Contribute ?
Robert Broyles
robert at poornam.com
Mon Feb 9 16:50:49 CST 2009
Leif Madsen wrote:
> Robert Broyles wrote:
>> Sorry in advance for any grammer/spelling mistakes. (I've been at it for
>> almost 18 hours now.)
>
> No problem! Thanks for getting this thread started. I have some ideas I'll be
> elaborating on in-line.
>
> Let me start that there has been some work going on in the background to get a
> new AsteriskDocs.org site up and running which would ideally become the
> 'de-facto' location for Asterisk documentation. However, that goal is a ways
> out, so lets start with just getting a site up :) I have been working on that
> in my spare time, and have also thought quite extensively about what that would
> look like, and have spoken to many people about the way forward.
>
Please let me know how I can be of assistance here. If we make
asteriskdocs.org the primary site, let's get something moving.
> I'll explain some of my thoughts throughout this email in response to your
> questions and suggestions.
>
>> My thoughts are basically this...
>>
>> 1) We can start from scratch, and create a new single wiki, which is
>> recognized as the most comprehensive guide to Asterisk.
>
> I've never really liked the idea of a wiki for the Asterisk community, because
> we already have one -- and it doesn't work. Most information is based on
> Asterisk 1.2, and has become quite stagnant, and is rarely updated. I think we
> need a new approach for Asterisk documentation that is not wiki based. At least
> for now.
If a Wiki won't work, fine. Just thought it would more readily enable
the Asterisk community to take part in adding content.
You mentioned most of the current information is based on Asterisk 1.2.
Perhaps we could have different tracks of the site, based on which
version you are using. So we would have a 1.2, 1.4, 1.6 track. It would
definitely help individuals to find the information they need - specific
to their running release of Asterisk.
>
>> 2) We can expand further on voip-info.org.
>
> Yes we could also do that. In fact I would encourage ANYONE to update
> voip-info.org in any way possible to help with the documentation front there.
> However, that is not the approach I wish to take. An Asterisk wiki already
> exists, and for whatever reason it hasn't worked until now. I'm not interested
> in duplicating effort using a method that hasn't proven itself (in the context
> of Asterisk of course -- it works great for wikipedia obviously).
>
Whatever we use, it needs to allow the community to easily add or edit
content. This is why I said Wiki. :-)
I think the biggest problem with the current wiki (voip-info.org I'm
assuming) ... is that it's more that just Asterisk. If there was one
wiki for Asterisk, that the whole community accepts as the Asterisk
Documentation 'Authority' - then I think everyone would be more willing
to contribute to it.
>> Regardless of which option we do, regular 'audits' of the documentation
>> is done, to ensure that the latest and most accurate information is
>> available.
>
> I agree, and I have some ways of making some of the things you mention below
> more readily available and up-to-date.
>
> One of the things I've found that causes a great deal of inconsistency and
> errors is the fact that was have documentation for Asterisk in many locations.
> We have the source code (documentation for dialplan applications, CLI commands,
> dialplan functions, manager commands, etc...), we have the 'doc' directory in
> the source tree, we have the voip-info.com wiki, and we have the O'Reilly book.
>
> I think the way to get all this information accurate, up to date, and consistent
> across the many platforms is to centralize the documentation somehow, or at
> least pseudo-centralize it. By doing this, we would be able to "update once,
> distribute many" so that all levels of documentation (whether they be in
> Asterisk software, in the O'Reilly Book, or on the Asterisk Docs website) are
> accurate and up to date.
>
> This is already somewhat possible. A few developers (lead by eliel on IRC from
> what I can tell), have started with creating an XML type markup in the Asterisk
> code base which allows the documentation from the dialplan applications and
> functions (and could then be spread to the CLI commands, Manager commands, AGI
> commands, etc...) to be exported out of the source code, and into things like
> HTML pages, PDF books, etc...
>
> Using this approach, we could use a web frame work like Drupal (to be consistent
> with the Asterisk.org site which is also Drupal based; my preference) and import
> the documentation from the Asterisk source code from the markup language, and
> get it into a web page available for wider viewing.
>
> From this approach, we could then use the PHP style commenting system
> (php.net), thereby allowing people to comment on errors, and provide useful
> commentary. Those comments could then be monitored by 'documentation marshals'
> who could then get the relative changes acknowledged upstream, put back into the
> Asterisk code base (central documentation repo), and from there, when the pages
> were rebuilt (nightly? weekly?) then the documentation on the Asterisk Docs site
> would immediately become up to date.
>
> Additionally, since A:TFoT (Asterisk: The Future of Telephony) is written in
> DocBook, we could potentially synchronize the documentation from the appendices
> with the documentation in the Asterisk source code, thereby keeping changes to
> the book in sync with Asterisk documentation, and vice-versa. This would be
> advantages as any update to the book would get pushed back down to Asterisk, and
> any updates to the Asterisk source would get pushed back up to the book. Both
> locations would benefit from this.
>
I love the idea of a Documentation Repo.
I'm not a developer, myself, so I don't understand all of what's said.
But it makes sense - "update once, distribute many." :-)
>> What information will be available?
>> Everything about Asterisk.
>> - Guide to setup/install of Asterisk (Using the Realtime Engine, AEL,
>> etc)
>
> I like this idea. I've been thinking of the Asterisk Docs website as a spot
> where articles could be contributed for guides of how to setup new features that
> are being contributed to Asterisk on a nearly weekly basis. Each new feature
> added could potentially have it's own guide (or at least article) in the site.
>
> I'd like to see this as kind of "extending" the book so that things that might
> not fit into the book, or which people want to know more about could have some
> sort of article or guide that extends beyond the introduction provided in A:TFoT.
>
>> - Troubleshooting/debugging guide, common issues and their
>> resolution, etc
>
> Again, a great idea, and could be a "book" of articles in itself. The Drupal
> framework makes this quite trivial as you can create a "book" inside, and then
> create pages that link up within the book framework on the site.
>
>> - Each dialplan application, explanation of it's use, it's
>> parameters/options, examples of use.
>
> See my lengthy description above of how I imagine this to be accomplished.
>
>> - depreciated functions, and detailed alternative methods
>
> This would really just be an expansion of the current documentation of dialplan
> applications, functions, etc... and simply needs us to update the primary
> locations of that documentation.
>
I am in agreement with all of this. Especially an brief article about
each new feature that's released. This opens the door for others to
further expand upon the documentation of that new feature.
>> Some of this stuff seems silly, but the point it to make the information
>> available to even the newbies. Someone mentioned in a previous thread
>> that alot of the information on voip-info.org is written for advanced
>> users, and it assumes too much about the reader, and their skillset.
>> This only leads to more silly questions from the reader.
>
> I can agree with that. I don't believe that lowering the barrier of entry for
> users is silly at all. That is actually how the Asterisk Documentation Project
> came to be, and from that, A:TFoT.
This is a primary focus for me. When I first started with Asterisk, I
didn't know anything. (I still don't know anything by the way.) But I
believe Asterisk to be the future of telephony, and communications. And
the more people that we can get excited about Asterisk, the better. If
we make it easy for anyone to get started, and empower them to find
their own resolutions / solutions - and in turn give back to the
community... well, that's what opensource is really about.
>
>> Anyway, this is my start. I am at least attempting to improve the
>> documentation on Asterisk. Anyone go any other suggestions?
>
> I have a few :) See above!
>
>
>
> So, how do we get where we want to go?
>
> The first step is really to get some sort of module for Drupal that allows the
> importation of documentation from DocBook (or some other XML type markup
> language like what is being used in the Asterisk source code) into the website
> so that we can start the process of 'centralizing' the source of documentation.
> We would use the Asterisk Docs site to give access to A:TFoT, and would further
> expand on that wealth of knowledge using articles and guides which would be in a
> CMS such as Drupal. From there, other pages of reference would be built and
> imported into Drupal (read only, commenting system available), but the source of
> the documentation would live in Asterisk source code. This way the documentation
> on the Asterisk Docs site is the exact same as the Asterisk source (and thus the
> same as what you would see when you type something like 'core show application
> Dial' from the Asterisk CLI).
>
> There is a module for Drupal called 'Book Import/Export' that may be the start
> of the framework for getting this information out of Asterisk source and into
> Asterisk Docs (see http://drupal.org/node/286592). However that module appears
> to be the start, and incomplete, so someone would have to take that on and get
> us a working module for our purposes.
>
If you can send me very detailed, 'technical' requirements for this, I
can pass it among our organizations developers. We have over 300
engineers and software developers - so I'm sure that we can figure
something out. :-)
> Any other suggests for CMS's that already have this functionality would be
> welcome, but I've been researching (lightly) for the last few months, and have
> yet to find anything that does this.
>
> That is where, IMHO, we have to start.
>
> Leif Madsen.
> http://www.asteriskdocs.org/
>
> _______________________________________________
> --Bandwidth and Colocation Provided by http://www.api-digital.com--
>
> asterisk-doc mailing list
> To UNSUBSCRIBE or update options visit:
> http://lists.digium.com/mailman/listinfo/asterisk-doc
More information about the asterisk-doc
mailing list