Shorter help pages?

This is not exactly a wish – more a case of pondering aloud. Does anybody feel there would be any benefit in having more, but shorter (or more narrowly focused) help pages?

Perhaps it is just that I always seem to use help when I’m in a desperate hurry and scrabbling around to try and find out how to do something. Sometimes this leaves me scrolling up and down, knowing that the subject must be on the page somewhere, but unable to find the crucial sentences that contain the information I need. Others may be calmer in their approach and less troubled by this

As I said, just pondering out loud.

Best wishes,

Martin BB.

Interesting, I suppose I am of the opposite strain. Little is more annoying to me than an involved application with a help file consisting of a dozen or two paragraph long “help” files that basically just state, in paragraph form, the title of a menu. I big part of this is that I hate clicking on stuff. Having to click eight times to read a series of material that would print out onto a single page is, frustrating. I’m not saying you are wrong, just that I’ve always quite enjoyed reading the help files for applications like BBEdit, EagleFiler, Scrivener, and DEVONthink. Stuff like Together’s help is so inaccessible behind a wall of clicking and clicking and clicking that it is useless to me.

I suppose it depends on how one uses Help, and what it is supposed to be for. What you describe to me sounds more like a user manual – something that you can read before you start using an application. In a way, I suppose I think of Help as needing an exclamation mark after it (i.e. “Help!”) – in other words, something that is used in an emergency when you need a very specific piece of information as fast as possible. In the latter case, I would think that shorter is better. Perhaps one could have both kinds of documentation – perhaps even much the same documentation available in two different formats.

All the best,


I think it is the exclamation point that makes the difference here. I usually access help at any time, I don’t just read and memorise prior to usage. Sometimes I’ll read documentation before I use something that requires meticulous setup (and then these are generally not what one would consider to be “user level” systems), but even after that point, always prefer a “sheet” of documentation to a forest of clicks. I’d rather skim a long page than repeating click links and back buttons to find something. What you say about not finding something is generally true for me too. I operate on a different logic base than the author, often, and thus do not know where something is. In a long page I can skim while using the trackpad to scroll. Negative results requires scrolling. With a forest help file, negative results require lots of clicking and moving the mouse up to back buttons and then back to link locations. It’s actually more work than reading and scrolling. This is aided when the long page contents are logical. If I know roughly how far down a menu command is that I’m interested in, I can rapidly scroll down until I get near it.

I wonder if a compromise to this might be an anchored mini-toc at the top of long pages, like Wikipedia does. If an article is long and broken into sections, it automatically makes a table of contents so you can jump straight to a particular portion of the article.

I can see why a lot of clicking would be tedious – I don’t much like it myself – but perhaps an example may help to illustrate my kind of problem. Not long ago I couldn’t remember if there was any option for synchronised scrolling in Scrivener windows. I did a search in help for the word “synchronise” and got (I think) a couple of hits. It then took a little searching to find that this was merely a word in a note somewhere at the bottom of a page which was about some completely different kind of synchronisation. I’m sure I could have been much more organised in my approach, but I suspect that some kind of brain operation might be needed before that becomes normal for me. No doubt people use help in very different ways, and I wonder if there might be some sense in trying to find out what people think of the present system, particularly as there is a new version of Scrivener coming up. I personally have had a real struggle to adapt to Scrivener, as I discovered it was much more complex than I first expected, and I didn’t find the help as helpful as I might have wished.

Best wishes,


Good point: shorter entries do mean more relevant search results. This is one of the tips I always give people when using Scrivener’s Binder.

I think a big part of the problem here is Apple’s, really quite daft, help system. That floating window with a weak search engine, lack of match phrase highlighting, and a format that makes cross-publishing a PDF as difficult as publishing a web site as a PDF, and the inability to have help files open from different programs at once. It is one of the most poorly thought-out UI aspects of OS X in my opinion. A big part of your problem would be solved by it doing something like Scrivener does, allowing easy two-stage searching both to a document and then within a document, either by skimming (for highlighted terms) or using Cmd-G to jump between them.

As for my thoughts on Scrivener’s help, it is hard to say because I’ve been around since before there was a help file. I’ve never really used it from the standpoint of getting help, but rather more to verify an assumption or to make sure I was offering forum support using standard nomenclature. The way I use it is probably not indicative—but I can compare the style to other applications I am not so heavily involved with, and I generally do feel more comfortable in a “document” as opposed to a forest, and it usually comes down to precisely the problem already expressed. Rarely do the author and I agree on where something should be placed, and so there is a degree of hunting involved. When it comes to hunting I prefer a document to a forest. I’ve always relied very heavily on document scale searching as I find Apple’s global search to be laughably inaccurate most of the time. In fact, my preference is an outboard PDF over Apple’s system at all. What I can do in Skim far out-ranks Apple’s help tool. So if anything, my preference would be even further from the lots-of-little-bits notion.

I’m curious on what other people think too, but you might have more success in another forum. I’m not sure how many people visit this board unless they have their own wish in mind. If you would like for me to move this thread some place else, just tell me where.

Please look that way -->

I am physically incapable of thought at this point. I keep trying, but nothing happens.

I’m afraid that as a one-man show (when it comes to coding and the Help file, that is - hello David!), the Help file ends up reflecting my own organisational systems. That said, I did look at how other big programs handle cutting things up - the way menus are organised into one-page-per-menu and so on - so Scrivener’s help file is fairly consistent with others. (Of course, programs with fewer menus and features have smaller help files.)
All the best,

My original thinking when I posted was along the lines of “Might this be an improvement that other people would find useful?” I’m not looking for benefits for me, but rather benefits for the program and/or other users. If people think the discussion is worth continuing in a place where it would attract more attention, then I would say by all means move it.

My own feeling is that Scrivener would benefit from a slightly different format of Help, but that is partly because of my approach to using programs. I have to admit that I find it very difficult to absorb documentation before I start using a program. My usual approach is to get the basics, dive in, and search Help as I go along. Having just started using Bookends, I have to say that I have found their approach to Help very useful. They merely have a PDF of the entire manual, and clicking on Help launches it in Preview. Searching from there brings up highlighted hits. It may seem a bit odd at first, but I find it works very well, and better than Apple’s own Help application, which, as you say, is very weak. Such an approach would solve my kind of problem, and would also allow Amber to have her long document (which could, of course, be opened in other applications if desired).

Anyway, I think there might well be value in getting feedback from people who actually use Help when they need help!

Best wishes,

Martin BB.

I agree. It’s used by many programs, and I find it the most practical way to get information.