On Mon, 2012-09-24 at 12:54 -0500, Steve Borho wrote: > On Fri, Sep 14, 2012 at 1:39 PM, Ross Boylan <[email protected]> wrote: > > 1. Is the manual intended to be self-contained, or does it assume > > familiarity with Hg? > > I suspect the answer is the latter, although 1.1 only mentions an > > assumed familiarity with Windows explorer and the reading guide 1.2 does > > not include any references to Hg proper. > > It assumes familiarity with Mercurial. I thought that was mentioned > in the preface. Explaining Mercurial's principles is a largish task. > > > A self-contained document would be ideal; failing that some reference to > > Hg docs would be good. Some of my confusion, for example which files > > are in a manifest and whether a revision includes all files, probably > > reflects my relative ignorance of Hg. Ditto for an understanding of > > branching and merging. > > Links to Mercurial documentation would be welcome. We even keep a > copy of the Mercurial book on our web site in HTML format. I think the installer also puts mercurial docs on the system; at least I have them. It's possible I got them from elsewhere, but I think (not on Windows now) they're on the Tortoise menus from the Windows start button. > > > 2. Program vs task-based documentation. > > Much of the manual is program based: if you click here you will get this > > menu, which does these things. As noted in my message on the specifics, > > sometimes "these things" aren't described well or at all. > > > > A task-based approach is often more helpful, especially for novices. > > 5.5-5.13 and 7 tend in that direction. However, the task-based > > information tends to focus on Hg-specific repository-level operations. > > The more vanilla version control tasks involved with the standard work > > cycle while working on a project, are not there: add, remove, delete or > > editing files and directories. commit is there. The specific task that > > got me into this, wanting to revert a file to a previous version, is not > > there (I know: probably the revert command; I wasn't sure if that > > operated on the repository or what its implications were for > > branching). I didn't see a discussion of branching and merging. > > A lot of the documentation just answers the question "what does this do?" If that :) > > > 3. Redundancy > > The same function is accessible in multiple ways, often from multiple > > context menus, some regular menus, and some toolbars. In the detail > > email I said it would be helpful to have detailed descriptions after the > > context menus. The problem is that detailed descriptions could also go > > elsewhere--and probably are often elsewhere, if I had hunted around > > enough. Perhaps there should be one spot with the commands fully > > documented and links to it from the appropriate places. > > I think it's always preferable to avoid redundancy. Less things to > update as changes are made, less opportunity for missing things that > need updating. There's a tension between wanting to show the answer wherever you are looking in the manual and avoiding redundancy. Perhaps the spot documentation could include a one line description and a link to a fuller description? The problem is the one line description then becomes a redundant part. I assume many functions can be accessed in many ways, e.g., explorer context menus, workbench menus, various workbench context menus.
I guess one alternative would be to list the function once and list the ways it can be accessed, but that's a much different organization than the manual has now. Whether it's friendlier or not depends on whether the reader is coming to the manual from a particular menu and wondering what it does, or coming to the manual with a task in mind (e.g., revert to previous version) and wondering how to do it. Ross > ------------------------------------------------------------------------------ Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ _______________________________________________ Tortoisehg-discuss mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/tortoisehg-discuss
