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