On 22 Nov 2010, at 18:00, Rajith Attapattu wrote:
On Mon, Nov 22, 2010 at 11:09 AM, Rajith Attapattu
<[email protected]>wrote:
Hi All,
Based on the questions asked on our user list and feedback from
customers
etc.. it seems that we have plenty of room to improve when it
comes to ease
of use and documentation.
Ease of use is one that directly impacts the first impression
about any new
product.
All,
I pretty much agree with these points, although with some
reservations about the one-size-fits-all packaging proposal...
I firmly believe this is something that needs to be one of the top
priorities (if not the top most) for our next release.
Perhaps it's time for us to take a step back and see if,
1) Have we packaged our products in a way that is useful for our
target
users ?
Given that we have products written in multiple languages and
targetted at
different Operating systems perhaps pre-compiled individual
components might
not be the most optimal.
Therefore downloading individual components doesn't really make
sense as you
need brokers, clients, examples and management tools, documentation
to get a
good all round experience.
Instead we should probably ship a single source tree with some sort of
script that will build the brokers, clients, examples and
management tools
and install the binaries to a particular location.
Easier said than done, but I believe several folks have expressed
their
desire about taking this direction.
Goo...?
I'm not sure about this. That doesn't seem like the usual model for
enterprise software distribution.
1. I agree that providing a full, DIY source bundle is something that
should definitely be provided, but in addition to other downloads. I
don't see why both models can't coexist?
2. It should be alongside componentised or modularised binary
downloads. The installable artifacts are the brokers and the
management console/command line tools, which should be available as
platform specific binaries, installable packages of various kinds,
and as a DIY source tarball, for Java and C++.
3. The second type of artifacts are the developer components, the
client libraries for various languages. These should be available as
components that can be installed into repositories or development
environments, such as Maven POM files or OSGi modules. The client
library for each language or environment should include the runtime
components, which may need to be installable, as well as providing
the artifacts that can be packaged with software being developed.
These three types of artifact multiplied by the available execution
platforms, languages, runtimes and environments (which includes DIY
or source tarball format) gives a formidable number of downloadable
artifacts, which must be carefully documented in order not to confuse
end users. For instance for the C++ broker, in addition to a DIY
source download there could be x86 RPMs, x86_64 RPMs, Solaris 10
SPARC packages, Win32 MSI installer, Debian and other Linux packages,
again in x86 and x86_64 variants, and so on.
I suspect a multi-level approach here is useful, from 'Beginner' to
'Advanced' levels, with appropriate artifacts provided. We obviously
need to decide *what* we support and stick to it as well as keeping
everything as simple as possible. Perhaps the Tomcat site could serve
as a model, since it also provides Java and cross platform Unix and
Windows code as both binaries *and* source. See here:
http://tomcat.apache.org/download-70.cgi
2) How easy is it for folks to download an install our products ?
If we can achieve the above, I think it will go a long way in
achieving this
goal.
Each download needs suitable and useful documentation to help the end
user get it running as fast as possible, possibly we should provide a
set of configuration files for the brokers as an additional set of
downloads or as part of a HOWTO series on the documentation. This is
not currently the case. For instance, I expect the site front page,
where it mentions python, to be clicky and take me to a page that
tells me about python support in Qpid, or lets me download the python
client. Currently it is not obvious what and this is a big fail.
3) How easy is it for people to run the examples and get it going?
Again, if we can get the above going, then it makes it very easy
for folks
to run the examples, preferably against both brokers.
See above, +1.
4) Have we organized our documentation properly?
I think we are on the right direction here. The new website and the
svn
based documentation is a big improvement.
We just need to ensure we continue to do so.
The idea has been floated of making a direct link from SVN to the
website. basically, we need to ensure there is a *stable* set of
pages that can be linked to and *added* to, as new features and
components are developed, and FAQs are answered or bugs fixed. This
used to be the wiki, and I have no problem with this for ad-hoc
documentation. However, I am happy for it to be a directory in
subversion that is synchronised to the web server with some SSIs for
template purposes, if that is more acceptable to everyone. We just
need to ensure that:
1. It *must* be easily and *instantly* editable. This is so that
there is a low barrier to developers documenting things and answering
questions in an archived publicly accessible place, otherwise
*nobody* will create any (useful) documentation.
2. Additionally the pages must present as a stable set of URLs that
do *not* vary with versions. This allows content to be indexed by
google and linked to from external sites - remember that people ask
google first, and we to be able to have answers to questions on
forums or stackoverflow and so on point to the Qpid site permanantly.
3. Finally, the Docbook files should be made available as XML with a
style-sheet or template that converts them to HTML + CSS for easy
browsing, again from a subversion directory, for easy and instant
editing again. This should be non-versioned, i.e. always pointing at
the trunk files, with a constant URL. The generated PDF files can be
archived after each release, but the current books will always be in
the same place.
5) Have we got enough documentation to cover atleast the basic
aspects?
I think we do this to a reasonable extent with the new "programming
with
apache qpid" document.
However there are some gaps that exist and we need to ensure we
fill them.
No, but see 3. above.
6) Have we got enough documentation to cover the topics that
people are
interested once they get the basics going?
I think the new documentation structure lacks this kinda of
documentation.
No, +1. This would be covered by 1. and 2. above.
If developers can make immediate, ad-hoc documentation easily, that
is permanent, they are more likely to. There *will* need to be a
proof-reading and editorial function that takes place at the same
time as building releases, probably, to ensure quality. The important
thing, though, is getting the content there in the first place. If it
is easy to do, we will document things that are interesting, or that
have been confusing us, on the spur of the moment, and that is
usually what the end users will want.
Also, there doesn't seem to be any Java API documentation. I know
this is mostly just JMS, but AMQConnection, AMQMessage and so on
should have generated Javadoc, with links to the 'javax.jms.*' Oracle
documentation too.
We also need more 'Integration' style documentation. How to muse Qpid
*with* other stuff, be that Spring JmsTemplate, EhCache over JMS,
SOAP over JMS and so forth. Possibly also Qpid interop capability,
with RabbitMQ and so on? I believe using Qpid with some of the other
Apache 'cloud' projects has been mentioned as something useful to
document as well? Not sure about the C++ side?
7) Are we releasing frequently enough for users to rely on us to
ensure
that critical bugs are fixed ?
No ! - ThankfullyJustin has volunteered some time (as per his
email to the
list) to get frequent releases.
At the minimum we need to do two major releases and two minor
releases per
year.
No, +1.
If we are doing quarterly releases, we need to define *what* we
release - it can't just be "whatever bugs we fixed since the last
release, plus some stuff that people were working on and happened to
finish in time". This means a well defined roadmap, at the very least
for the next release, but possibly out to the next year - why not,
since we don't *have* to commit to the later features? There can be a
roadmap feature list for the very next version, and also a wish-list
or nice-to-have list for the versions after that? This could even be
driven by JIRA, similar to the blockers list Robbie put up for this
release?
This then needs documented in big letters somewhere. For example, how
are people supposed to work out that Qpid is aiming to be AMQP 1.0
compliant? It is alluded to, sort of, but there is nothing about time-
scales or feature sets or which broker or client is expected to
implement it first, and what that might mean, for interop etc.
8) Do we as a project have a process that defines how we handle a
critical
issue after a release ?
I don't believe we have such a process at all. We need to first get
into the
habit of getting frequent releases and then see how we can do this
sort of
emergency fixes.
I think we should be building the 'development' version more
regularly, if we are going with the odd/even numbering scheme. This
means there should be a 'nightly' of 0.9 being built every day, and
available for download, with big warnings about unstable code. This
way we exercise the release/build process more frequently, and get to
see the state of the code long before release time. And, this way
emergency fixes become easily available to users the day after they
are checked in, and we can also promote a nightly build to an
emergency RC if required...
I am positive that our community (both developers and end users)
has a lot
of good ideas.
I am quite keen on hearing suggestions/comments about the above
topics.
I will start by replying to my email with what I think about the
above
questions :)
Cheers,
Andrew.
--
-- andrew d kennedy ? apache qpid project : http://qpid.apache.org/ ;
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
