[rabbitmq-discuss] Thoughts from a new user

[Jon Brisbin]

On Sep 18, 2010, at 4:52 PM, Matthew Sackman wrote:

> _I_ am distinctly unhappy about the fact that if homebrew continues to
> become more popular, more and more RabbitMQ users are going to be
> installing it without the documentation. We put time and effort into the
> man pages, and I will _always_ refer to locally installed documentation
> in preference to websites: you should always be able to trust that the
> locally installed documentation matches the version of the software you
> have installed.

I guess we'll have to agree to disagree on how developers use documentation. I can't speak for others, but I don't use man pages unless I'm forced to. When I'm developing, I have about a dozen tabs open with the various documentation sources I need while I'm developing. I use online documentation *exclusively*. I do have a few things with documentation installed locally. Spring framework and the Java SE API docs being the two I use most frequently. But I usually do that because they're so big.

For everything else, I always, always, always use the resources available online. I do that because I switch back and forth between the official docs and googling for examples. I mix other sources in with official documentation. I can't do that if I'm locked into less on a terminal. 

Sorry to burst your bubble, but I *really* hate man pages. I use them for finding out what options I need to pass to a program because it's been a while since I've used it and I don't quite remember. For that, they're really handy. I don't use them for anything else.

> Some software, in e.g. Ubuntu LTS releases, or Debian
> Stable releases, can be 5 years old and no, I would not expect the
> authors to clutter their websites with historical records of past
> documentation.

Having old versions of things on their website is an expectation I have. Maybe it's unrealistic. I can see no downside to having old versions of documentation hanging around for users of older versions of the software. If you put the version of your documentation in a position:fixed nav box somewhere on the page, you've addressed the problem of being half-way through a page of docs and forgetting what version you're looking at. 

When you write the documentation, if you cover a new feature introduced in that version, you simply put a "since: 2.1.0" or something. If enough of these are sprinkled throughout, people get used to that easily and understand that this feature was introduced in version 2.1.0. The python docs are great examples of this.

> I would however expect to be able to install the
> documentation, if it isn't already, via the package manager, and know
> that it matches the version of the software I have installed.

I think that's reasonable, but I go back to agreeing to disagree on what format most developers prefer to use documentation in. Erlang folks I think are a little skewed because of the prominence of Emacs, info docs, and the really old school conventions that are perfectly functional but aren't taking advantage of new possibilities.

> There are other optional dependencies of Erlang, for example X Windows.

Uggh. X. Don't get me started on that! :)

> I can't see any
> evidence of X Windows at all looking through the homebrew list at
> http://github.com/mxcl/homebrew/tree/master/Library/Formula/.

Thank heavens! :)

XQuartz is awesome and everything I need in an X distro.

> Again, the
> correct solution is demonstrated by Linux distributions which for
> example have both erlang and erlang-nox packages thus allowing you to
> choose which is installed. Then RabbitMQ can depend on erlang |
> erlang-nox. In fact, in modern linux distributions, Erlang has been
> split up into many smaller packages so that packages really can express
> precisely which parts of Erlang they depend on, which bits are
> optional, and which bits have no bearing at all on the package.

I do like this because it really burns me that I have to install X on server machines that will never have an X session run on them because it's a dependency.

> Over the last 20 years, Linux distributions have honed package managers.
> It's no surprise that these days rpm and deb systems are comparable in
> power in terms of package management and are extremely capable. _I_ am
> frequently amazed at how incapable package management is on other
> platforms.

I wish there were aptitude for Mac. If someone wants to really make Mac developers happy, they'd port apt to OS X and have a little GUI to download binaries, like you suggest.

Until such time I'll use Homebrew because it takes up less space on my harddrive and has fewer "parts" to keep track of.

> IMHO, most of the pain caused by macports is only addressed by
> homebrew's packages _seeming_ to do the absolute minimum required to
> make something compile at the cost of excluding (almost?) all optional
> features and components.


I can't speak for anyone else, but having every possible option turned on by default is the reason I don't like macports. The fact that Homebrew does exactly what you've pointed out is why I like it! :)

Thanks!

J. Brisbin
http://jbrisbin.com/






-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rabbitmq.com/pipermail/rabbitmq-discuss/attachments/20100918/84337cfe/attachment-0001.htm>