[rabbitmq-discuss] Thoughts from a new user

Sun Sep 19 09:19:28 BST 2010

On 19 Sep 2010, at 00:59, Matthew Sackman wrote:

>> On Sep 18, 2010, at 4:52 PM, Matthew Sackman wrote:
>> 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.
> 
> Heh, yeah, I hear you about size. Also, I generally prefer info pages to
> man pages as they can be cross-linked etc. I also have dozens of tabs
> open too - but e.g. frequently to
> file:///usr/share/doc/$PACKAGE-docs/html/... etc. There's no good reason
> why HTML documentation can't be installed locally. Also, never
> underestimate the utility of M-x man $PACKAGE in emacs ;)

I also echo the fact that Man pages are usually the last place I look, reading properly formatted
HTML is a lot easier, I can even read it on my phone on the train if I wish.

> 
>>> 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.
> 
> Sure, I understand what you're saying. I think it's reasonable to have
> documentation a few revisions back, but if you then have a massive
> rethemeing or rebranding exercise, do you really want to slog through
> the 60 releases you've made over the last 5 years? There are maintanence
> tradeoffs. E.g. you choose to rewrite a paragraph because it's not
> clear. The functionality that the paragraph describes hasn't changed for
> N revisions. Does the paragraph need applying to all N copies of the
> documentation? I know these sound like trivial issues, but whatever
> policy is agreed on should be applied consistently, and when you're in a
> team of just 6 full time developers, these things take a substantial
> toll on man power.

If you are concerned about the branding or something like that, look into Sphinx or
something equally powerful. It will save time for your developers in the long run.

I am not sure that I want it to go many versions back - usually the last point releases
and whatever is supported in the major distros. For example, a lot of people won't be
installing 2.x just yet, and will be a mix or 1.7 and 1.8

>> Until such time I'll use Homebrew because it takes up less space on my
>> harddrive and has fewer "parts" to keep track of.
> 
> My only fear with that is that eventually people may get bitten by
> missing features which were disabled simply because it would make
> compilation more tricky. What is it about homebrew that you think will
> prevent it from turning into macports again? Are they actively trying to
> avoid supporting anything other than the simplest configuration of each
> package?

Maybe it is a lack of understanding, but I have seen MacPorts do some really weird
things to my OS X machines. I am hoping that homebrew will be the apt of OS X
but I doubt it, as it requires a level of knowledge of what is happening further in the 
development of the operating system and lets face it Apple don't care.

> 
>> 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! :)
> 
> I think the users should have the choice. Neither system offers that.

True.

Tim.