Posted: Sat Feb 26, 2005 3:46 am Post subject: [Asterisk-doc] Is this being done?
Hi all,
I often field simple questions on IRC and I have a lot of macros to show
links to docs and most of these are the the older manuals on
asteriskdocs.org. where you can directly jump to "The dialplan", for
example.
Without being one of the RTFM! people, I do go into "see the
links/google/wiki" mode when it's obvious that the person doesn't even
know what a dialplan *is* or the first thing about the need for one. I
strongly feel that these folks NEED TO READ the existing docs,
especially, those that you are so ardently working on.
Now, to my point. Sometimes, it isn't easy to search for stuff that has
no name. Example, suppose you know or have seen ${EXTEN:2:5} but don't
know what the second number means. I tried to search for this, first by
looking for the old ways like "stripLSD+deprecated". Unfortunately, the
stuff that came up showed that much and no more.
Shouldn't the new solution always be mentioned when something is no
longer used instead of saying, "oh that's deprecated, don't use it!" ?
Thats' about as useful as "this has been discussed many times" in the
mailing list :)
Part two, is there an effort to have the *definitive* text on variables,
which would include *all* the related expressions like :n:n (you see,
what *is* that called?) If it were a function it'd be SubStr(). So, is
the section on variables going to have every bit of knowledge there is
to know about the current use of variables? I don't think it does now,
but I haven't looked for a while.
If a subject with such limited scope (variables - no pun intended) isn't
completely covered, then people asking the simple dialpaln questions on
IRC can say "I already read all those" with impunity and it makes for a
lot of unanswered questions.
Posted: Sat Feb 26, 2005 6:39 am Post subject: [Asterisk-doc] Is this being done?
On Sat, 2005-02-26 at 12:46 +0100, Randy Resnick wrote:
Quote:
Now, to my point. Sometimes, it isn't easy to search for stuff that has
no name. Example, suppose you know or have seen ${EXTEN:2:5} but don't
know what the second number means. I tried to search for this, first by
looking for the old ways like "stripLSD+deprecated". Unfortunately, the
stuff that came up showed that much and no more.
I know exactly what you mean, as just a couple of weeks ago I went
searching for that very thing, in an effort to document it better. Leif
found that that not only was it not documented, but it had a serious bug
in it as well. I still don't know what to call it, but it is being
documented as part of our project. It's also been added to Asterisk's
documentation (see below).
Quote:
Shouldn't the new solution always be mentioned when something is no
longer used instead of saying, "oh that's deprecated, don't use it!" ?
Thats' about as useful as "this has been discussed many times" in the
mailing list :)
I agree. I hope to get the docs to the point where we can point people
to "see section 4.3 in the docs" instead of "RT(non-existant)M".
Quote:
Part two, is there an effort to have the *definitive* text on variables,
which would include *all* the related expressions like :n:n (you see,
what *is* that called?) If it were a function it'd be SubStr(). So, is
the section on variables going to have every bit of knowledge there is
to know about the current use of variables? I don't think it does now,
but I haven't looked for a while.
Currently, the best we have is the README.variables file in the doc/
subdirectory of the Asterisk source. Luckily, Olle was kind enough add
documentation for the ${EXTEN:-5:3} syntax when we fixed the bug that
Leif found.
Quote:
If a subject with such limited scope (variables - no pun intended) isn't
completely covered, then people asking the simple dialpaln questions on
IRC can say "I already read all those" with impunity and it makes for a
lot of unanswered questions.
You've cut to the heart of the reason we started the documentation
project. And just so you know, we are still working hard behind the
scenes on getting these sorts of things documented. Thanks for keeping
us focused on making sure the simple things are well-documented. We
appreciate your input!
Posted: Sat Feb 26, 2005 6:58 am Post subject: [Asterisk-doc] Is this being done?
Quote:
You've cut to the heart of the reason we started the documentation
project. And just so you know, we are still working hard behind the
scenes on getting these sorts of things documented. Thanks for keeping
us focused on making sure the simple things are well-documented. We
appreciate your input!
Well, as they used to say to drummers in the band, "Someone has to drive
the truck!" The only thing I can do is point people to the docs and let
you know when I see "seperated" used. Most of the times people have said
"I read all those" they are either very poor readers (or Eng. second
language) or full of ${EFFLUVIA}. "Dialpan? I don need no stinking
dialplan. How do I..."
Posted: Sat Feb 26, 2005 9:25 am Post subject: [Asterisk-doc] Is this being done?
On Sat, 26 Feb 2005 12:46:17 +0100, Randy Resnick <randulo@ssl-mail.com> wrote:
Quote:
Hi all,
Ahoi!
Quote:
Now, to my point. Sometimes, it isn't easy to search for stuff that has
no name. Example, suppose you know or have seen ${EXTEN:2:5} but don't
know what the second number means. I tried to search for this, first by
looking for the old ways like "stripLSD+deprecated". Unfortunately, the
stuff that came up showed that much and no more.
Shouldn't the new solution always be mentioned when something is no
longer used instead of saying, "oh that's deprecated, don't use it!" ?
Thats' about as useful as "this has been discussed many times" in the
mailing list :)
I agree. Unfortunately the people who do the programming and write the
"documentation" or instructions, aren't always very clear (just ask
Jared). A better effort of trying to keep stuff like that up to date
is a logistical problem that I'm not sure the answer to. I've had
people saying things lately such as, "Documentation needs to be easier
to find" and "Asterisk needs more centralized documentation". Thats
what we're trying to do with the AstDocs project, unfortunately with
only a handful on contributors, those needing documentation far
outweigh those who can and will write it (although docs wouldn't be a
problem if the scales weren't tilted in such a way :))
Quote:
Part two, is there an effort to have the *definitive* text on variables,
which would include *all* the related expressions like :n:n (you see,
what *is* that called?) If it were a function it'd be SubStr(). So, is
the section on variables going to have every bit of knowledge there is
to know about the current use of variables? I don't think it does now,
but I haven't looked for a while.
Jared is currently working on such an effort, so yes, there is a push
towards having something like this.
I spoke with Mark briefly, and he calls the :n:n a substring, so that
is what we're going to call it as well.
Quote:
If a subject with such limited scope (variables - no pun intended) isn't
completely covered, then people asking the simple dialpaln questions on
IRC can say "I already read all those" with impunity and it makes for a
lot of unanswered questions.
I agree. I've found myself trying to figure out how to do something
in the dialplan and making it very complicated until someone told me
about some unknown variable which would have made it simple.
Posted: Sat Feb 26, 2005 10:18 am Post subject: [Asterisk-doc] Is this being done?
Quote:
I agree. I've found myself trying to figure out how to do something
in the dialplan and making it very complicated until someone told me
about some unknown variable which would have made it simple.
My original tactic, about one year ago, was to print and read the
original doc you guys wrote cover to cover, skipping anything I didn't
care about (like say ISDN or h323). I did that a few times and had a
good idea of what could be done, but no experience. Kinda like a sex
education class, but no experience. This knowledge allowed me to ask
slightly less idiotic questions on IRC (and we if follow the sexual
analogy, who are those answering?) which was important.
I think I'm a decent reviewer, so I keep coming back to see if there's
anything new.
So to a new point: how about an RSS for asteriskdocs.org. Although I see
a lot of yawn material done in RSS, this is one case where it'd make
sense. It's very easy to do RSS 2.0, the hard part is someone entering
the link when something changes :)
This list, as nice as it is, doesn't relace an RSS feed if thgat were
only to announce when a new doc section were available to inquiring minds.
Posted: Sat Feb 26, 2005 10:37 am Post subject: [Asterisk-doc] Is this being done?
On Sat, 26 Feb 2005 19:18:45 +0100, Randy Resnick <randulo@ssl-mail.com> wrote:
Quote:
My original tactic, about one year ago, was to print and read the
original doc you guys wrote cover to cover, skipping anything I didn't
care about (like say ISDN or h323). I did that a few times and had a
good idea of what could be done, but no experience. Kinda like a sex
education class, but no experience. This knowledge allowed me to ask
slightly less idiotic questions on IRC (and we if follow the sexual
analogy, who are those answering?) which was important.
I think I'm a decent reviewer, so I keep coming back to see if there's
anything new.
Awesome, we appreciate review and critique!
Quote:
So to a new point: how about an RSS for asteriskdocs.org. Although I see
a lot of yawn material done in RSS, this is one case where it'd make
sense. It's very easy to do RSS 2.0, the hard part is someone entering
the link when something changes :)
This list, as nice as it is, doesn't relace an RSS feed if thgat were
only to announce when a new doc section were available to inquiring minds.
!!!
Wow, I've been asking for this for about 2 weeks now :) The AstDocs
site recently implemented an RSS feed for SineApps (in my attempt to
start centralizing Asterisk documentation and news) and I had an idea
which I was hoping someone would be willing to tackle.
First, to answer your asteriskdocs.org RSS feed question, one exists.
Its a bit hidden, but you can have an AstDocs RSS feed from:
http://www.asteriskdocs.org/backend.php
I will try and make a point of announcing when new documentation is
released. No guarentees I will catch everything though. If someone
wants to monitor AstDocs for changes and the CVS list for
documentation (filter usually for README.*) and post to the main
AstDocs webpage, please email me off-list and we can discuss.
Now, back to my RSS idea.
What I would like to have is an RSS feed on the AstDocs site (its easy
to add multiple RSS feeds to Xoops, so that isn't a problem), for
bugtracker related posts. I would like two separate (getting better at
spelling that right :)) threads from the bugtracker; newly added bugs
and bugs with recent activity.
I already know a few people who are looking for this, but
unfortunately I don't really have the time right now to program
something like this. Its probably not TOO hard, but its just the time
I don't have right now to learn it.
What I would like to have is an RSS feed on the AstDocs site (its easy
to add multiple RSS feeds to Xoops, so that isn't a problem), for
bugtracker related posts. I would like two separate (getting better at
spelling that right :)) threads from the bugtracker; newly added bugs
and bugs with recent activity.
I already know a few people who are looking for this, but
<look type="possible dropped ball">You weren't you asking me about this
earlier, were you?</look>
I was going to look at coding this, but then I forgot... :)
Posted: Sat Feb 26, 2005 12:57 pm Post subject: [Asterisk-doc] Is this being done?
Quote:
I was going to look at coding this, but then I forgot... :)
May I steal this line?
"I was going to think about maybe doing something, but I forgot to think
about it."
Wow, so much like my customers it's not funny.
Really though, glad to see someone interested in contributing. If I had
more time I would do more, too much work is a good problem to have to
worry about though.
That's because we're running a CMS called Xoops which I'm not entirely
familiar with. If you happen you know where I have to go to add this
in the CMS, then please let me know and I will add it.
I don't have console access to the box either, so I personally am
limited to changes allowed through the CMS administration.
Thanks for the tip, you're right, that would be the best solution,
unfortunatly I don't know how to add it.
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