On Mon, Sep 18, 2017 at 6:00 PM, Pavel Lyalyakin
<pavel.lyalyakin_at_visualsvn.com> wrote:
> Hello,
>
> On Fri, Sep 15, 2017 at 11:57 PM, Johan Corveleyn <jcorvel_at_gmail.com> wrote:
>> On Thu, Sep 14, 2017 at 5:27 PM, Pavel Lyalyakin
>> <pavel.lyalyakin_at_visualsvn.com> wrote:
>> ...
>>> I've spent some time to materialize the Quick Start document that I
>>> think will be helpful for novice SVN users. At the moment, it provides
>>> the most basic guidance which should be enough for "quick start".
>>> However, it lacks "Viewing the history of changes" section that is not
>>> ready yet. As of merging, I'd better provide a link to relevant
>>> SVNBook sections. Merging is not a basic topic and should not be
>>> described in a Quick Start guide, IMO.
>>
>> Hi Pavel,
>>
>> Nice! I've done a quick scan and it looks good in general. I'll try to
>> go through it in detail this weekend, if I find some time.
>>
>> Your "quick start" is much larger than the old one (so we have to be
>> careful that it's still as short as possible, to be "quick"), but I
>> think it's good that you added some explanation of the basic concepts,
>> and try to take the user along the most basic commands. The old "quick
>> start" was more in the style of "here is some bait, don't be afraid to
>> give it a try, and look for more docs". But now that I've read your
>> patch (diagonally), I like it.
>
> Thank you. :)
>
> I consider the current patch as a basis for further work on this
> document. I am not comfortable with rolling out a patch for
> non-discussed document. But if we agree on the structure and topics
> that should be covered, it is going to be easier to compose the doc
> and review it.
Ack. I didn't get around to a detailed review last weekend, and am
totally swamped during this week, sorry. Maybe one of the other people
on this list can go through it and provide some feedback?
Otherwise, maybe I can pick it up again next weekend or the week after.
>>> I'm attaching two patches. I would greatly appreciate a review,
>>> comments and suggestions. Here we go:
>>> 1. svn-quick-start-eol-native-v1.patch.txt
>>> Log Message:
>>> [[[
>>> Add missing svn:eol-style=native property to publish/quick-start.html
>>> ]]]
>>
>> Sure, of course.
>>
>>> 2. svn-updated-quick-start-v1.patch.txt
>>> Log Message:
>>> [[[
>>> * publish/quick-start.html:
>>> Updating the SVN Quick Start guide as suggested in
>>> https://lists.apache.org/thread.html/ea3462042131baac9c702fd4f19ae292c25ef20527d27db449e90f0e@%3Cdev.subversion.apache.org%3E
>>> ]]]
>>
>> Okay, I'll try to go through it in detail.
>>
>>>> > The question is: what kind of topics should the quick start page cover?
>>>> >
>>>> > My idea is that the page should provide task-based guidance for SVN end user on
>>>> > how to
>>>> > * checkout a working copy,
>>>> > * update the working copy,
>>>> > * modify the data in the working copy and commit it,
>>>> > * make a branch or tag,
>>>> > * perform a simple merge.
>>>>
>>>> Sounds terrific.
>>>>
>>>> The current quickstart page focuses on "how do I quickly set up a my
>>>> own little repository, locally (with file:///) and put some stuff in
>>>> there". Like a beginning user / student / ... perhaps would like to
>>>> version his own files. I think it's a good way to introduce the
>>>> concepts of repository and working copy, and help them get started by
>>>> versioning some of their own files locally.
>>>
>>> SVNBook has a High-Speed Tutorial that provides such instructions:
>>> http://svnbook.red-bean.com/en/1.8/svn.intro.quickstart.html
>>
>> Yes, I know. But still, I think it's important to have quick
>> instructions on our own webpages. Also, the quickstart in the book
>> only shows unix-style examples, and our quickstart page shows both
>> unix and windows examples. I think that's important.
>
> I think that Windows-style examples could be easily added to the
> suggested version of the document. For example, we can add two
> versions of these examples. Note that the examples in the current
> version of the document should work both on *nix systems and Windows.
> There is one example specific to *nix, though:
> [[[
> Direct access: file://var/svn/repos/MyRepo/MyProject/trunk
> ]]]
Indeed, maybe we should add the Windows version of that command too.
Come to think of it, we should probably mention that there are popular
GUI clients out there, so people not comfortable with the command line
shouldn't be turned off (though we're providing only the command line
examples, as the basic mode of working / lowest common denominator,
which can easily be transposed into GUI actions by most users).
>>>> Do you think you can start from that "setup", and continue with the
>>>> topics you listed above? Or would you like to take a different angle?
>>>
>>> I'm thinking about taking a different angle. I think that the document
>>> should assume that a remote Subversion repository is already in place
>>> and the user simply wants to start working with the existing versioned
>>> data. Or he wants to import non-versioned data to the new remote
>>> repository or repository sub-path.
>>>
>>> In my experience, a beginning user or a student already has a
>>> repository that he access via HTTP(S) or svnserve protocol. For
>>> example, a first-year student gains access to his private SVN
>>> repository and never has to use file:// schema or `svnadmin` tool.
>>> There is another case, when a user should first request to create a
>>> repository for him or for his project (here is an example:
>>> http://information-technology.web.cern.ch/book/how-start-working-svn/requesting-new-svn-repository).
>>> He won't use file:// schema and `svnadmin` in this case, too.
>>
>> Hm, okay, I guess you're right concerning "most beginners already have
>> a server setup for them". OTOH, those are the users that often have
>> local people to help them, and documentation / faqs / ... written by
>> their administrators tuned to the local setup.
>
> I think that we should back those local people and administrators with
> some kind of quick reference. It should be helpful for them when they
> write the documentation tuned to their setup. That's where quick start
> help should come in handy -- the won't have to dive deep in SVNBook.
+1
>> So I'm not sure about dropping the "how to make your own local
>> repository with file:// and track your own personal files" entirely.
>> It's a good way to get a bit of introduction to the repository side of
>> the story too (and it's a bit of a neglected use case of svn: track
>> your own files locally). Maybe we can add an extra section (after the
>> ones you already added) about this. Somewhat optional, in the sense of
>> "if you're interested to set up your own local repository to
>> version-control your own files, here is how to do it". Just thinking
>> out loud ...
>
> Yep, we don't have to drop that section. The current version of this
> section is OK. However, I would rework it bit. It requires a comment
> for every command that users run, IMO. I'm not sure about the name of
> the repository "my-repos", too. For me, this name assumes that there
> should be multiple Subversion repositories under "my-repos". But it is
> not the case here. I'd use MyRepo or MyProjects. The first one assumes
> that this is a SVN repository, the latter one assumes that there can
> be multiple projects in a single repository.
+1.
Comments inline, or next to the commands, should certainly help there
(as long as they don't "overwhelm" (maybe avoid comments on actions
that are mostly self-evident?)).
For the name of the repository I'd say MyRepo (or my-repo) then. I
think the name "my-repos" was shorthand for "my-repository",
abbreviating after the 's' in repository, not intended as a plural
form. But you're right, that might be confusing, so +1 for ending in
"repo". The name MyProjects sounds a bit too high-level for me, and
steers the user a bit in a direction that might be different from what
he wants to use it for.
--
Johan
Received on 2017-09-18 23:43:23 CEST