Posted: Mon May 01, 2006 7:08 pm Post subject: [asterisk-doc] Proposal - documentation subject matter exper
Asterisk Friends,
It was good to see some activity at the doc list. I agree that something needs to be done with the documentation.
I would like to have some feedback about the following idea:
Identify people that would like to become a documentation subject matter expert. Some potential projects are: ZAP, SIP, H323, Dialplan, Fax, IAX, etc. They do not need to have the ability to code. Reading code to some extend would be great.
Create a modular manual that provides all the information that people need to know to get asterisk (based at subject) up and running. Take SIP as an example. I think that a good description of NATs and Firewalls could avoid a lot of questions and would give a better understanding about how the channel needs to be configured. To be able to keep up with development is it required that ‘writers’ and developers ‘talk’ so that the new development can be put in the right documentation perspective. It would be great if the developer would be willing to review the modifications that have been made to the documentation. This would improve the quality of the documentation.
Another advantage could be that the documentation could be ‘tested’ together with the software. This would again improve the quality of the documentation and could also encourage people to become an active tester of the software. This means that the whole project would benefit.
I think that at a later stage needs to be discussed about the infrastructure that should be used. Let’s start to create content.
I don’t mind to step up for the SIP subject.
Looking forward to your comments,
Henk
Posted: Tue May 02, 2006 3:51 am Post subject: [asterisk-doc] Proposal - documentation subject matter exper
On 5/1/06, Henk <henk@osocoms.com> wrote:
Quote:
It was good to see some activity at the doc list. I agree that something
needs to be done with the documentation.
:)
Quote:
I would like to have some feedback about the following idea:
Identify people that would like to become a documentation subject matter
expert. Some potential projects are: ZAP, SIP, H323, Dialplan, Fax, IAX,
etc. They do not need to have the ability to code. Reading code to some
extend would be great.
I think this is probably a pretty good idea. While everyone really
will be able to look at everything, it probably becomes not so
practical. If someone wants to take on a specific area and get that
section started, then all the better. Although, at this point, I'd
just like to see some participation from some people in any area that
they feel they can contribute. If some people want to take the
initiative and designate themselves to a particular area -- all the
better! I'll probably pick the DUNDi area.
Quote:
Create a modular manual that provides all the information that people need
to know to get asterisk (based at subject) up and running. Take SIP as an
example. I think that a good description of NATs and Firewalls could avoid
a lot of questions and would give a better understanding about how the
channel needs to be configured. To be able to keep up with development is
it required that 'writers' and developers 'talk' so that the new development
can be put in the right documentation perspective. It would be great if
the developer would be willing to review the modifications that have been
made to the documentation. This would improve the quality of the
documentation.
Hrmmm... not entirely sure how to do this right now. Developers are
already pretty busy, and asking them to take on any more work is
probably just not possible. However, I'm sure most developers would be
happy to answer intelligent questions about certain areas, but I think
a bunch of documentation is going to have to be done through trial and
error. If we can get some of the developers to participate though --
all the better!
Quote:
Another advantage could be that the documentation could be 'tested' together
with the software. This would again improve the quality of the
documentation and could also encourage people to become an active tester of
the software. This means that the whole project would benefit.
Agreed -- this would be nice. It would be really nice to get
documentation on new features are they become available. By doing it
right away when the feature is new means that if someone is testing to
write documentation all the functionality of that feature will
probably be more thoroughly tested than usual -- thus increasing the
quality of Asterisk on the whole. Plus, since things tend to be
"forgotten" over a period of time, doing it right away will allow the
features to become recognized and not lost in code.
Quote:
I think that at a later stage needs to be discussed about the infrastructure
that should be used. Let's start to create content.
Well, that is basically happening now with Peter working on a new
documentation format. From there we need to discuss and vote who will
become the "experts" for a certain area, and thus have commit rights
to that area(s).
In the mean time, if you write documentation, please create a patch
and submit it to the mailing list. Someone will then patch their local
system, perform proofreading and error checking, then post their
changes (if needed) back to the list -- once we have a good patch,
then one of the core members will merge your changes into the
documentation. Once we've seen a few good patches, then that person
can be nominated for commit access.
Quote:
I don't mind to step up for the SIP subject.
Excellent! Looking forward to some of the things you get written!
Leif Madsen.
_______________________________________________
--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