[rabbitmq-discuss] Thoughts from a new user

[Matthew Sackman]

> 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 ;)

> > 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.

> 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.

Yeah, I don't think that's at all unreasonable. It depends on the style
of the documentation. For something like the extensions page, yes, I
think that would work well. For something like the clustering guide or
pacemaker guide, where the documentation is prose, I think it would
break the flow and so for stuff like that, I'd probably prefer to have
entirely separate versions of the page.

> 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.

By the same token, I hope you'll allow me to say that maybe OS X users
are equally skewed ;) Personally, I think good integration with the
editor is really powerful: eclipse and other IDEs are excellent examples
of this. Emacs isn't /great/ at it, but it's, as you say, perfectly
functional. The key requirement is that any documentation can be
searched very quickly and efficiently. Man pages work well as leaves
(simply because they can't be anything else). I would agree that having
something like the Java API docs as man pages would be a horror show if
you didn't know what you were looking for, but being able to just type
"man HashTable" is _much_ faster than using a webbrowser.

> 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?

> 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.

Matthew