Re: [Asterisk-java-devel] Help Vampires: A Spotter's Guide

[Stefan R. <ste...@re...>]

Hey Martin,

thanks a lot for yor work!
I've posted a short notice to the AJ homepage to announce the FAQ.

> the responses too. I'm still slightly new to Maven -- is there any way to
> build the site without all of the compilation and tests being run before
> that?

I don't think so. The site contains the test results and javadocs so
that has to be compiled. But once you get used to the APT format (ever
forget the leading space? :) you don't need too much cycles.

> Also, I found an erroneous HTML paragraph tag in one of the other documents,
> and made a little sentence above the first tutorial on the tutorial page. I
> think people often skip the tutorial page once they see it starts with
> FastAGI, and they don't know what they are looking for is just below that
> section.

Good idea. I think one source of confusion are the differences between
FastAGI and the Manager API (live) and the different use cases. Some
people just look for simple IVR stuff while others want to build
click-to-call like applications or notification apps. Maybe we could add
some example use cases to the FAQ to answer the question "What is the
difference between FastAGI and the Manager API?".

> Unfortunately, I fought and fought with APT to get it to correctly generate
> internal anchors on the tutorial page; I referred to
> http://maven.apache.org/doxia/format.html, but their example does not seem
> to work, so I ended up working around it by directly linked to the anchors
> non-automagically. I'd love if it someone could figure that one out --
> Google showed me that it had been a bug in the past, and a commonly-reverted
> one that shows up again for Apt. They claim it is fixed at the moment, but I
> have my doubts after my episode with it :).

Hmm maybe we can have a look at one of the maven sites to see how they
do it (if they do).

> change, so I left it alone. I also toyed with modifying the main "Home" page
> -- I think it might be good to combine the top little paragraph that starts
> with "The Asterisk-Java package..." and the "status" section, so that there
> aren't so many single-sentence paragraphs. I think people get lost in that
> front part and don't read/use it (a lot of newcomers don't understand the
> differences between the AMI/AGI parts of Asterisk, and that first paragraph
> does kind of try to explain it briefly).

Feel free to change anything there you like.
Another thing related to this that has been in my mind for some time is
our target group. I guess we have almost 100% market share accross
asterisk users that are also java developers. Thats quite nice but this
group is relativly small.
In addtion there are:
- Asterisk users who are not Java developers
Those are usually users of PHP or other scripting languages, I don't
think there will be much interest in Asterisk-Java.
- Java developers who are not Asterisk users
Those might be interesting. Guys who want to do some telephony/VoIP/..
stuff and have a Java background but don't know how to get started. So
this might be a target group with slightly different needs regarding the
docs on our site - at least some pointers at what Asterisk is about, why
it's cool, and how to get started.

> I've read that designing sites and pages on the www is a lot like being a
> billboard designer -- you're trying to hit your users as they go by at
> highway speeds ;).

Oh yes... There a few things we could do better with the whole page. On
the hand I like to have the blog stuff on the front page but on the
other hand I am not sure it doesn't steal attention from the really
important parts.
Then we have multiple "sites" - one per released version plus the
development snapshot and the linked /latest directory. While I think
it's important to have access to the documentation of older versions the
way we currently handle this also adds confusion.

Oh and happy easter :)

=Stefan