Documentation from a newbie's perspective.

Get help with installing, upgrading and running Asterisk.

Moderators: muppetmaster, Moderator, Support

Documentation from a newbie's perspective.

Postby lardconcepts » Sun Nov 08, 2015 3:49 am

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 https://www.asterisk.org/ just gives me

"Apache + PHP are rock solid".

Chaning to http://www.asterisk.org/ and drilling down to http://www.asterisk.org/get-started, well the third link takes me to http://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 https://www.digium.com/training/asteris ... s-training and https://www.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:
https://www.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.
lardconcepts
Newsterisk
 
Posts: 35
Joined: Tue Nov 11, 2014 2:13 pm

Return to Asterisk Support

Who is online

Users browsing this forum: No registered users and 9 guests