Pushing after merge considered harmful

Eli Zaretskii eliz at gnu.org
Tue Jan 26 21:00:03 GMT 2010


> From: Jason Earl <jearl at notengoamigos.org>
> Cc: Eli Zaretskii <eliz at gnu.org>,  bialix at ukr.net,  bazaar at lists.canonical.com,  "Matthew D. Fuller" <fullermd at over-yonder.net>
> Date: Tue, 26 Jan 2010 13:19:22 -0700
> 
> To be honest I find the idea that Bazaar might want to borrow
> documentation tips from git simply ridiculous.

No one was suggesting that.  The suggestion was to have a *good*
documentation, not a ``git documentation''.

> The primary reason that
> I *don't* use git is that I did not want to have to learn what my VCS
> was doing under the covers to get some work done.  Git's documentation
> covers its object model right after the Introduction, for crying out
> loud.

Yes, it's a bad idea, and no, Bazaar docs shouldn't do that.

But if some options cannot be explained without introducing the notion
of the history DAG, then by all means introduce it where those options
are documented.  Such options are not useful to non-programmers
anyway, so placing that description in some appendix is all that's
needed to satisfy the nerds without spooking the uninitiated.  Since
modern documentation is almost never read linearly, the fact that this
stuff is stashed in an appendix doesn't hurt anyone who needs to get
to it, provided that there's enough index entries and hyperlinks that
will lead there quickly and efficiently.

> That sort of documentation might appeal to the sort of people that build
> their own editor from parts using Emacs Lisp[1], but I really do not
> think that this is the target audience that bzr should be aiming for.

If you mean that the ``target audience'' are _only_ people who run
away when they see acronyms such as DAG, then I think you are losing a
very large part of your _real_ target audience.  The trick is to write
documentation that caters to all kinds of your potential users.  Just
separate them so that the people who don't need to read the advanced
stuff never stumble upon it unless they want to.

> [1]  I happen to use (and love) Emacs, but I stopped pretending a long
>      time ago that the modern Emacs community was in any way shape or
>      form "typical."

Well, typical or not, they are now intensive users of bzr, so I hope
you will not banish them from your target audience on ideological
grounds.



More information about the bazaar mailing list