On Sun, 19 Dec 2004, Ben Collins-Sussman wrote:
> On Dec 19, 2004, at 11:06 AM, Robert P. J. Day wrote:
> > again a bit more possibility for confusion, when it shows how to
> > import a "project" to initialize a repository. is it clear that
> > there is a 1:1 correspondence between a repository and the "project"
> > it represents? that's not explicitly spelled out here, but it's
> > certainly implied.
>
> Does it matter?
i think so as it's not clear whether a repo can contain more than
one "project", and people coming from a CVS background may implicitly
equate a SVN "project" with a CVS module (that's what i did the first
time i ran across the term).
page 13 of the PDF book talks about a repo with two "projects", calc
and paint, but i don't see where the word "project" has been
technically defined. is a project simply a subdirectory of a
repository? or is it a more formal object that has to be initialized?
this is the kind of ambiguity that makes it sometimes hard to ask
questions if you're not sure which term you should be using. (that
is, if i have a problem checking something out, would i post that i'm
having trouble checking out a repository, or checking out a project?
like i said, i'm being pedantic, but i'm a big believer in precise
terminology.)
> > it's also pretty clearly implied that a repository should always
> > contain the three top-level directories branches/, tags/ and trunk/.
> > more on this shortly.
>
> That's a deliberate implication, since it's a suggested standard.
> > p. 13:
> > the sample repo here seems to disagree with the rules presented just
> > a few pages earlier. here, we have a repo that contains *two*
> > software projects (paint and calc) and, on the next page, there's
> > a depiction of those projects.
>
> Aha.
ok, what revelation have we just had here? :-) so you do appreciate
the potential confusion that the sample repo with calc and paint has
no trunk/ directory, even though you've strongly recommended doing
just that a few pages earlier. never mind, keep reading.
> I think there's a meta-problem here.
>
> Originally, the chapter 1 "quick-start" example didn't exist at all.
> The book followed a nice logical progression:
>
> * Chapter 2 merely introduced the concepts of working copies and
> repositories. It made no suggestions or proclamations about "how
> many projects" lived in a repository, or what the branch/tag
> structure of a repository should look like. The examples were
> designed to be as simple as possible.
no problem there, but i think you *still* need to at least define the
terms if you're going to use them. and what might be useful, even in
a quick start chapter, is to show maybe two or three sample
repositories, including a truly realistic one that incorporates more
than one project (just showing it graphically, that's all.)
> * Chapter 4 first introduced the concepts of trunk/branches/tags
> structure.
>
> * Chapter 5 first introduced the idea of deciding how many projects to put
> in a repository.
i'm sure that, when i hit those chapters, it will all become clear.
i'm just pointing out that, at this moment, i'm nervous that i don't
quite understand the precise terminology (see my later email for
another example), and i'm worried that, as i keep reading, a small
misunderstanding on my part might be making me misunderstand more as i
go along.
> But then a whole class of users -- those who demand learning by
> example ("bottom up"), rather than reading a long "top-down"
> presentation over many chapters. So we added the chapter 1
> quick-start section as a way to get these people started... and
> hopefully those folks follow all the pointers throughout the quick
> start to the relevant chapters.
>
> So I'm not sure how to resolve this tension: put the quick-start
> into an appendix, and merely mention it in chapter 1? Would that
> help? It sounds to me like you're a 'top-down' reader who's busy
> trying to infer meaning in every little detail you see. Things
> might have been smoother for you if you had never encountered the
> 'quick start' at all.
i'm not convinced. i think there's a distinction to be made here.
depending on what kind of reader i am, i think it's fine if i read a
typical quick start chapter and think, "well, i don't think i got much
out of that, so i'll keep going." and that's fine.
what's not so fine is to read a quick start chapter and, as i continue
reading, to get confused because what i'm reading now seems to
*disagree* with what i read earlier. that's quite different.
i'll keep going and it may all become clear shortly. but, in any
case, i'm one of those people who, even if i don't get the details
right away, i want a clear idea of the big picture, along with the
pieces that go into it, that's all.
more later, after i spend some more time with this.
rday
p.s. i think that even "bottom up" readers need to have a clear
definition of the terminology, so that they can converse with others.
but i'll give this some more thought.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Sun Dec 19 20:55:09 2004