Documentation from a newbie's perspective

Asterisk Asterisk Support
1

I realise that once you’re familiar with a project, it’s very easy to say “oh, well that info is right over here - just RTFM dude”…

But I just thought I’d give my experience from a “newbie trying to learn his way around the docs” perspective…

Starting at asterisk.org/ just gives me

“Apache + PHP are rock solid”.

Chaning to asteriskdocs.org/ which is “Asterisk The Definitive Guide”, based on 1.8 which is already “end of life”.

There’s a link to purchase the 4th edition, based around Asterisk 11, but in the “why has v14 been pushed back” explanation, it’s made clear that A13 was a significant update.

Then there’s the Wiki - loads of info in there but it would be good to have an explanation of how it should be read.

For example, is “Asterisk 13 Documentation > Asterisk 13 Command Reference” supposed to be read “on top of” (ie: to supplement) the main wiki documentation?

I would also like more info on what version some pages are specific to.

Then there’s a link to “asterisk essentials” training at digium.com/training/asterisk/fast-start, which are both unstyled because all the css and js assetts in that page are 404, as are pretty much all the pages linked to, for example:
digium.com/products/busines … s/mobility

This isn’t meant to be a complaint; and the standard response of “well no-one is stopping you forking and improving the documentation” doesn’t really work in this case, if I don’t know how the documentation is meant to be written and read.

Anyway, those are my newbie observations - and yes, I know Google is my friend, but I’m not exaggerating when I say that most of the results of examples I’ve found date from 2006. Yes, I know you can narrow dates down, but it’s almost as if A13 is an exclusive club, designed only for insiders.

In other words, I find myself reading what I think is current documentation, but half an hour later find that “oh, it could be done far better using pjsip and this script”. It’s a bit like trying to learn Python - there’s so much documentation out there related to the dead 2.7 version that it takes a long time to build a comprehensive collection of Python 3.4 docs!

If I’m wrong and there’s a “Asterisk 13 Quick Start” or even an A13 based book that I missed, that would be an excellent start!

Finally, a LOT of times when I try and post a new post of follow a notification, I get a phpbb error with just “information - return to the index page”. Takes about 5 or 6 attempts to get the posting box up.

2

Hi
Almost 2 years has passed since this post was submitted. Now I’m doing a project based on Asterisk and my experience is very much the same.
I am trying to implement Asterisk v14.6.0 for our customer service, I’m 2 months in the project so I’m very committed now. I’m struggling with the documentation from sources mentioned by @lardconcepts and I make very small progress due to lacking the skill of debugging outdated examples.

I don’t wont to start a new thread asking this, so I put my question here, is there a documentation for current version of Asterisk? I would really appreciate it.

3

I don’t want to be rude but most of the new comers see asterisk like a tool that can be learned in two months, guess what is not.
If you(not you I’m speaking in general) want to create a simple PBX setup for your project, for your company or just for fun go and download FreePBX or any other GUI available out there. Asterisk is a huge toolkit for telephony and it handles a lot of protocols that you need to understand at least at a basic level in order to know how things work.

If you want to be an expert pay for a Digium course there is no better method the get into Asterisk and all the magic behind it, usually the FOSS community thinks that since the software is free the knowledge must be free too, yes, of course, you can learn asterisk by yourself, using google, seeing videos and following recipes but you will walk slowly.

I have near 11 years using asterisk and I’m not even close to being an expert, I only use SIP, sometime IAX2 and that’s all so please if you guys are frustrated go in a serious way and invest in knowledge. Pay a course or a consultor.

The documentation is all in the wiki, conf files and google!

4

@navaismo I agree with you, knowledge is expensive, one way or another price is always high.

For me asterisk is a piece of software, yes its huge, yes it has been developed for a very long time. But every piece of software needs manual, examples and so on… What good is an update if a user cant follow updated features? Should I build my system on asterisk 1.6 to learn on examples provided? Should I learn it for 10 years in order to be able to choose right technology for me?

As for Digium courses, sure, I will attend them, but when paying 3000$ I expect to extract as much as possible form the course, its not really possible when I cant ask the right questions, I cant ask them if my knowledge is null or based on system from 2010 (or older).

As any project, my project starts small and simple, but it wont remain this way. I would really like to use asterisk because it has plenty features I can use later on. I am not expecting to be learned, to get working solution nor to be held by hand doing whatever I do, rather I would be very happy about getting directions, pointers. Documentations and examples are a start, good book even better start. Advices are always golden. If its not what FOSS community is all about than I dont know what is.

5

One of the things we hope to be building on in the future are reference use cases[1] which provide a scenario and build it using modern Asterisk features. The one that currently exists, Super Awesome Company, is already on the wiki with a description and also has configuration[2] in the tree. If there’s other things we can improve then please comment on the wiki appropriately. One of the things I’ve found is that we do have good documentation for lots of things (the amount I reference it has increased a lot) but just having people able to find it is hard, even after reorganizing and trying to tweak things.

[1] https://wiki.asterisk.org/wiki/display/AST/Super+Awesome+Company
[2] https://github.com/asterisk/asterisk/tree/master/configs/basic-pbx

6

I’m wondering if this applies to every new knowledge that you want to learn, for example, Math. When you were a Kid and didn’t know how to sum did you ask your parents for documentation or after getting the course you knew what to ask? Is the same with all the courses that you will take in your life including an Asterisk training they will guide you to learn and to ask all your questions that you will have at the end of the day or the course.

And all of that is out there in the wiki, in the forum, on google, in blogs, etcetera, etcetera. We are getting used to recipes and we slowly forgot how to research :frowning:

7

FOSS is about letting you see how the code works at a deep level, not about high level overviews.

8

True, it applies to me and probably many others.

Thank you @jcolp for the links.

@david551 What are FOSS communities about than? I guess this would be an off topic discussion.

EDIT:
I wish to add, that I’m glad that this forum is alive, I guess my work with Asterisk has only begun, nice to know there is a community behind the project.

9

Well, I was wondering about this documentation, and when I was building asterisk from sources I noticed recommendation to make progdocs, so I have all the documentation I needed. It might be obvious to every one who is experienced asterisk / linux admin, but I am neither of those so was very happy to find it.
How to get it (for noobs like me):

Go to your sources directory (its /usr/local/src/asterisk-14.6.1 for me)
cd /usr/local/src/asterisk-14.6.1
if you made some builds before do
[sudo] make clean
than
[sudo] ./configure [options]
[sudo] make full
[sudo] make install
after that (if you dont have doxygen) install it via apt or yum
[sudo] apt install -y doxygen
(it might require some other packages, just follow error messages while doing next command)
and generate docs
[sudo] make progdocs

docs are in doc directory, for me its /usr/local/src/asterisk-14.6.1/doc
I copied whole doc directory to my /var/www/html/ so I could browse it by web browser and installed apache from apt. As far as I know, this are documentation to the version one has built, in my case 14.6.1 but if you build 13.X.Y docs will be for 13.X.Y

EDIT:
Noob tip: when you are playing with config files use some version control system. I use mercurial, just hg init && hg add in /etc/asterisk, commit on success, revert on failures, saves lots of time :blush:

1 Like