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