Hello,
On Tue, Sep 19, 2017 at 12:42 AM, Johan Corveleyn <jcorvel_at_gmail.com> wrote:
>
> 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.
Got it. I'm thinking about making a new version of the patch taking
your suggestions into consideration till the end of the week. I guess
that I will send them in a separate new "[PATCH] ... thread" per patch
submission guidelines
(http://subversion.apache.org/docs/community-guide/general.html#patches).
That would be the correct way to send the patch to the mailing list
for a review.
> >>> 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).
Got it. Thanks for the suggestion.
> >>>> 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.
Got it. I agree that MyProjects is indeed a bit high-level and does
not help to understand that it is a repository.
--
With best regards,
Pavel Lyalyakin
VisualSVN Team
Received on 2017-09-20 17:28:24 CEST