Hello, On Tue, Sep 19, 2017 at 12:42 AM, Johan Corveleyn <jcor...@gmail.com> wrote: > > On Mon, Sep 18, 2017 at 6:00 PM, Pavel Lyalyakin > <pavel.lyalya...@visualsvn.com> wrote: > > Hello, > > > > On Fri, Sep 15, 2017 at 11:57 PM, Johan Corveleyn <jcor...@gmail.com> wrote: > >> On Thu, Sep 14, 2017 at 5:27 PM, Pavel Lyalyakin > >> <pavel.lyalya...@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
