* Getting Started -- make a better tutorial
* Installation -- Make sure it is accurate
* Language Reference -- Could be expanded a bit, add AEL in
* Config File Ref -- Needs to include all possible config files
* Features
* Application Reference -- Not 100% done, but getting there.
* Asterisk Internals -- how does Asterisk work? Maybe get a guest
developer to write and we'll edit?
* FAQ -- pretty weak right now.
Like Ian or Ira said earlier, the Book is great, but we need to build a
reference manual.
I don't know how it all works, and the search stuff doesn't work yet. I'm
confident we can get it there, but I need help.
Beckman
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Beckman
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Wed Jul 12, 2006 5:06 pm Post subject: [asterisk-doc] Web-based Documentation -- Need Help
The thing to avoid is to write what has already been covered elsewhere. What
goes in asteriskdocs should be what is missing from A:TFoT.
We are working on a cookbook for O'Reilly, which will not hit the shelves
for a while; so rest assured there is writing going on, just not here. I do
not have enough bandwidth to write more than I already am, but I would be
delighted to provide some editorial assistance. People probably don't
realize how an editor can fix up a lot of the stuff that makes people think
they can't write. If someone takes the time to write something, even if it
has poor grammar and spelling mistakes and would upset your English teacher,
it is no big deal. That can easily be fixed during the editing process.
One person I think we should try to rope in is Ira. He say he can't write
but from what I have seen I beg to differ ;-). Also, he has some good ideas
about what was missing from A:TFoT, which is exactly what we want to move
towards.
A section of all the asterisk functions, and neat stuff that can be done
with variables would be useful.
"A child is the ultimate startup, and I have three.
This makes me rich."
Guy Kawasaki
--
Quote:
-----Original Message-----
From: Peter Beckman [mailto:beckman@purplecow.com]
Sent: July 12, 2006 12:46 PM
To: Asterisk Documentation Project List
Subject: [asterisk-doc] Web-based Documentation -- Need Help
Guys --
I've put a lot of work and effort into the web-based
documentation, but as of late nobody has offered to help
(other than a translation or two).
Is asterisk-docs dead?
I know we all have our own stuff to do, as do I, but if
you're on this list, there's a reason.
Can I get some help? I'll get SVN access for whomever will
help, but I need some backup here.
* Getting Started -- make a better tutorial
* Installation -- Make sure it is accurate
* Language Reference -- Could be expanded a bit, add AEL in
* Config File Ref -- Needs to include all possible config files
* Features
* Application Reference -- Not 100% done, but getting there.
* Asterisk Internals -- how does Asterisk work? Maybe
get a guest
developer to write and we'll edit?
* FAQ -- pretty weak right now.
Like Ian or Ira said earlier, the Book is great, but we need
to build a reference manual.
I don't know how it all works, and the search stuff doesn't
work yet. I'm confident we can get it there, but I need help.
Beckman
--------------------------------------------------------------
-------------
Peter Beckman
Internet Guy
beckman@purplecow.com http://www.purplecow.com/
--------------------------------------------------------------
-------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Wed Jul 12, 2006 6:00 pm Post subject: [asterisk-doc] Web-based Documentation -- Need Help
On Wed, 12 Jul 2006, Jim Van Meggelen wrote:
Quote:
The thing to avoid is to write what has already been covered elsewhere. What
goes in asteriskdocs should be what is missing from A:TFoT.
I disagree. While it makes no sense to write what can be copied, I think
having a location to have as much as possible is the goal.
Quote:
We are working on a cookbook for O'Reilly, which will not hit the shelves
for a while; so rest assured there is writing going on, just not here. I do
not have enough bandwidth to write more than I already am, but I would be
delighted to provide some editorial assistance. People probably don't
realize how an editor can fix up a lot of the stuff that makes people think
they can't write. If someone takes the time to write something, even if it
has poor grammar and spelling mistakes and would upset your English teacher,
it is no big deal. That can easily be fixed during the editing process.
Amen. Editors are needed.
Quote:
One person I think we should try to rope in is Ira. He say he can't write
but from what I have seen I beg to differ ;-). Also, he has some good ideas
about what was missing from A:TFoT, which is exactly what we want to move
towards.
A section of all the asterisk functions, and neat stuff that can be done
with variables would be useful.
Have you actually looked at what I've done? It is there, just not as
filled out as I think it needs to be:
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Wed Jul 12, 2006 7:18 pm Post subject: [asterisk-doc] Web-based Documentation -- Need Help
Quote:
-----Original Message-----
From: Peter Beckman [mailto:beckman@purplecow.com]
Sent: July 12, 2006 2:01 PM
To: Discussions regarding The Asterisk Documentation Project
Subject: RE: [asterisk-doc] Web-based Documentation -- Need Help
On Wed, 12 Jul 2006, Jim Van Meggelen wrote:
> The thing to avoid is to write what has already been covered
> elsewhere. What goes in asteriskdocs should be what is
missing from A:TFoT.
I disagree. While it makes no sense to write what can be
copied, I think
having a location to have as much as possible is the goal.
I agree, but A:TFoT is already there, so why repeat that? I guess our goal
was to produce an Asterisk library, so since we have the first book (and
it's audience covered), why not move on to the next thing.
The audience for the next book that the docs project should address would be
those folks who have successfully gotten Asterisk up and running, and want
to take their skills to the next level.
Quote:
> We are working on a cookbook for O'Reilly, which will not hit the
> shelves for a while; so rest assured there is writing going
on, just
> not here. I do not have enough bandwidth to write more than
I already
> am, but I would be delighted to provide some editorial assistance.
> People probably don't realize how an editor can fix up a lot of the
> stuff that makes people think they can't write. If someone
takes the
> time to write something, even if it has poor grammar and spelling
> mistakes and would upset your English teacher, it is no big
deal. That can easily be fixed during the editing process.
Amen. Editors are needed.
Writers are needed more!
Quote:
> One person I think we should try to rope in is Ira. He say he can't
> write but from what I have seen I beg to differ ;-). Also,
he has some
> good ideas about what was missing from A:TFoT, which is
exactly what
> we want to move towards.
>
> A section of all the asterisk functions, and neat stuff that can be
> done with variables would be useful.
Have you actually looked at what I've done? It is there,
just not as
filled out as I think it needs to be:
I did indeed. One of the concerns that I had was that it appeared to have a
lot of duplication. I am not saying that that is a bad thing, but I would
want to be absolutely clear on who the audience is. From that it will be a
lot easier to understand what belongs in the book, and what does not. Trying
to be all things to all people caused us a lot of problems early on in the
docs project. The task was just too huge. If there was one thing we
determined to do in future efforts, it was to state the audience for a
particular volume, and make sure we stayed within that parameter for all
effort within that scope.
Jim
--
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.1.394 / Virus Database: 268.9.10/386 - Release Date: 12/07/2006
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Wed Jul 12, 2006 8:46 pm Post subject: [asterisk-doc] Web-based Documentation -- Need Help
On 7/12/06, Jim Van Meggelen <jim@vanmeggelen.ca> wrote:
Quote:
> Have you actually looked at what I've done? It is there,
> just not as
> filled out as I think it needs to be:
>
> http://mph.gotdns.com:82/manual/en/
I did indeed. One of the concerns that I had was that it appeared to have a
lot of duplication. I am not saying that that is a bad thing, but I would
want to be absolutely clear on who the audience is. From that it will be a
lot easier to understand what belongs in the book, and what does not. Trying
to be all things to all people caused us a lot of problems early on in the
docs project. The task was just too huge. If there was one thing we
determined to do in future efforts, it was to state the audience for a
particular volume, and make sure we stayed within that parameter for all
effort within that scope.
Exactly! So what IS the scope of the web documentation? We already
have doxygen documentation hosted on the Asterisk.org website -- so we
don't need to cover documenting the actual functions in Asterisk --
that is already being done (although I'm sure they would love some
help fleshing some of it out from people with the know how)
What really seems to make sense for the web portion (and what I
envisioned from the beginning) is the ability for someone to type in
either a dialplan appliction or function, get some information about
it, and a simple dialplan example of how it works (a la PHP's function
search). The PHP site also has the ability for people to comment and
provide their own examples, situations and issues with a particular
function -- and this is the kind of thing I'd like to see.
The wiki makes no sense for this kind of behaviour, but with the PHP
style documentation it's a perfect forum.
So as Jim states -- a narrow, focused scope is required. You will not
be able to be everything to everyone -- we tried it, and it simply can
not, and will not, work. You will become easily overwhelmed, and
instead of contributing, as you obviously want to, there will just be
too much to do, and things will come to a grinding halt.
My suggestion is to take what I've proposed and start with that -- it
would be a huge benefit to the community! I'd love to be able to just
go to a website and type in the dialplan function or application I'm
looking for, get some information on it, and a simple example of how
to use it, and its options. That'd be a huge step forward, and
something that is totally doable!
Leif Madsen.
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Thu Jul 13, 2006 2:12 am Post subject: [asterisk-doc] Web-based Documentation -- Need Help
On Wed, 12 Jul 2006, Jim Van Meggelen wrote:
Quote:
> I disagree. While it makes no sense to write what can be copied, I
> think having a location to have as much as possible is the goal.
I agree, but A:TFoT is already there, so why repeat that? I guess our
goal was to produce an Asterisk library, so since we have the first book
(and it's audience covered), why not move on to the next thing.
Because (a) it's not in a web-friendly format, (b) it's searchable only
within Acrobat, (c) Google doesn' index it, (d) there is no Table of
Contents.
I think the content is great, but accessability and organization is
needed.
If we get to the point where stuff we're writing is covered in your book,
I'll formally ask permission to skim it for inclusion.
Quote:
The audience for the next book that the docs project should address would
be those folks who have successfully gotten Asterisk up and running, and
want to take their skills to the next level.
And that's great -- I'm building a reference library. If you need to know
something about extensions.conf, there is a section for you. If you need
to know the current working parameters for Dial, they are fully
documented on a single page.
Quote:
Writers are needed more!
Sure, but as you've pointed out, a lot of documentation is already
written, it just is spread all over the place -- the wiki, the docs in the
Asterisk code, the A:TFoT book, etc. I'm working on trimming and
unifying, so editors are very useful.
Copy-and-pasters are good too!
Quote:
> Have you actually looked at what I've done? It is there, just not as
> filled out as I think it needs to be:
>
> http://mph.gotdns.com:82/manual/en/
I did indeed. One of the concerns that I had was that it appeared to have a
lot of duplication. I am not saying that that is a bad thing, but I would
want to be absolutely clear on who the audience is. From that it will be a
lot easier to understand what belongs in the book, and what does not. Trying
to be all things to all people caused us a lot of problems early on in the
docs project. The task was just too huge. If there was one thing we
determined to do in future efforts, it was to state the audience for a
particular volume, and make sure we stayed within that parameter for all
effort within that scope.
I'm not looking to write a book. Books can quickly fall out of date, as
you've said. When you wrote the book, 1.2 wasn't even out, and now we're
at 1.4, and the book hasn't been updated. This is a reference manual.
I want this documentation to be an ever-evolving beast, that updates as
the code changes, documents change-in-user-interface history, etc. It
keeps up and outlines new features, etc.
Much of the work and framework is already done. Now it just needs to be
filled out, some more automation built, and some coordination with
developers to make sure the docs stay up to date with the code.
The audience? Anyone who is using asterisk. It's a reference manual that
includes simple installation procedures, caveats, and simple usage
examples for coding Asterisk.
Beckman
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
Posted: Thu Jul 13, 2006 2:43 am Post subject: [asterisk-doc] Web-based Documentation -- Need Help
On Wed, 12 Jul 2006, Leif Madsen wrote:
Quote:
Exactly! So what IS the scope of the web documentation? We already
have doxygen documentation hosted on the Asterisk.org website -- so we
don't need to cover documenting the actual functions in Asterisk --
that is already being done (although I'm sure they would love some
help fleshing some of it out from people with the know how)
Doxygen isn't friendly, except to us geeks. Those graphs? Not useful
when I'm writing an extensions.conf dialplan. Where is the docs on
Dial()? Can I just type "dial" in the search box and it come up with the
docs? Oh wait, no search box. Show me a page that looks like this in
Doxygen:
How are #include files relevant to me using Dial() in my dialplan?
Quote:
What really seems to make sense for the web portion (and what I
envisioned from the beginning) is the ability for someone to type in
either a dialplan appliction or function, get some information about
it, and a simple dialplan example of how it works (a la PHP's function
search). The PHP site also has the ability for people to comment and
provide their own examples, situations and issues with a particular
function -- and this is the kind of thing I'd like to see.
That's my goal. But why not make it just as comprehensive as the PHP
documentation? http://php.net/manual/en/ Includes Install, Language
Reference (needed less for Asterisk, but AEL, variable usage and modifiers
go there), etc. That mother is comprehensive, and that's what I think we
both love about it.
Quote:
The wiki makes no sense for this kind of behaviour, but with the PHP
style documentation it's a perfect forum.
So as Jim states -- a narrow, focused scope is required. You will not
be able to be everything to everyone -- we tried it, and it simply can
not, and will not, work. You will become easily overwhelmed, and
instead of contributing, as you obviously want to, there will just be
too much to do, and things will come to a grinding halt.
I have no problem breaking things up for people who are easily
overwhelmed.
I need people for each of these areas:
* Continuous Updating Application Reference to meet with current code,
both in SVN and released -- includes monitoring svn-commits list
* A masterful coder who can write scripts to scrape out things from the
current Asterisk code base, such as .conf samples, and being able to
determine when an Application came into or fell out of the code (ie
0.x, 1.x < 1.2 or 1.x >= 1.2.9)
* Anyone who wants to grab stuff from the wiki and find a good place
for it in the organizational structure
* Editors -- people who check to see if the docs are correct and well
written, suggest changes, etc.
It can't be all done at once, this is an ever-evolving project. It's
going to be somewhat thin until we get a base we are all proud of and
people start using. THEN we'll start filling portions out, updating, etc.
Quote:
My suggestion is to take what I've proposed and start with that -- it
would be a huge benefit to the community! I'd love to be able to just
go to a website and type in the dialplan function or application I'm
looking for, get some information on it, and a simple example of how
to use it, and its options. That'd be a huge step forward, and
something that is totally doable!
That part is already done -- enter "Dial" in the "search for" box at the
top of the page, and Voila. I just need some people to step up to copy
the DocBook code generated by one of the Asterisk developers and edit it
into the current code to finish up the Application reference.
With that, we can launch this puppy. The question is, where...
Beckman
---------------------------------------------------------------------------
Peter Beckman Internet Guy
beckman@purplecow.comhttp://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
You cannot post new topics in this forum You cannot reply to topics in this forum You cannot edit your posts in this forum You cannot delete your posts in this forum You cannot vote in polls in this forum