[RFC] proposed user doc for nested trees

[Maritza Mendez]

On Thu, May 7, 2009 at 9:17 AM, Ian Clatworthy <
ian.clatworthy at internode.on.net> wrote:

> I've spent today putting down on paper how *I* would like nested 'items'
> to look from a UI perspective. Not all of this will arrive in the
> initial cut but I wanted to dig deep enough so that we could debate the
> initial design in a broader context.
>
> There are a few tweaks to the current UI suggested by this
> documentation. The main one is to to drop the 'reference' term and just
> use 'nested' everywhere I think it is needed. So in particular, that means:
>
> * join --reference => join --nested
> * reference * => nested *
>
> It's not a big deal but I feel this will make things a little more
> consistent for end users (who know nothing about the internal 'tree
> references' naming). Right now, --reference is a hidden option to join
> and the reference command is only days old, so I don't feel compelled to
> retain backwards compatibility here.
>
> Naively, most of the suggested enhancements are small to implement
> though I'm sure the overall work - including tests - is quite large.
> (The main one which worries me is the proposed propagation of new
> locations, but that might be shot down in any case.) As I said, not all
> of it will make whatever we deliver in the initial cut.
>
> I hope that the vision presented makes sense both from a end-user model
> and task efficiency perspective. IMNSHO, if we deliver this, Bazaar will
> have the nicest implementation of this feature around. But my opinion
> isn't what matters - it's yours! To make feedback easier, I've attached
> both the patch and a PDF version of the proposed section (7.5) of the
> User Guide.
>
> Enjoy,
> Ian C.
>

Ian:

I read your draft during a particularly boring meeting on Friday. :)  I made
some notes, but nothing major.  I have three things I would like to say:

1. This is really well written.  That's a talent.  Thank you for sharing it.
I would watch out for colloquialisms (like "no-no") which might not
translate well, but that is minor.

2. I agree that --nested is better than --reference.
Why use two words when one will work?  "Nested" says what it is.
"Reference" is too generic and bzr already has plenty of that with
"references" to parent and push/pull branches.

3. I expect nested to confuse users.  No matter how it is implemented
someone will complain.  I personally plan to use it a lot and I expect to
have the manual open at all times.  This is a sophisticated feature and the
reader needs to pay close attention.  Your draft implies this in a few
places, and I think it's ok to come right out and say it.

-M
-------------- next part --------------
An HTML attachment was scrubbed...
URL: https://lists.ubuntu.com/archives/bazaar/attachments/20090509/db043f8a/attachment.htm