Scrivener's manual - skim the fat

I’m writing hot on the trail of beginning to read Scrivener’s manual. It’s 600 pages long pdf document, the language feels overly profuse, overly nuanced. I see the long hours of labour amplified with pleasure that the author (who is also the developer) put into this work making extensive use of every feature of the app itself. However, I can’t but note that software manuals usually don’t exhibit unnecessary wordiness because the point of such a manual is not to become a literature work in its own right which this manual obviously makes obvious. As sophisticated as this application is it’s not worth 600+ pages. In any case, it’s not as steep as Indesign or Premiere Pro. Short, simple sentences, bullet-point style of exposing functions and features, concise sentence-building would add more to general understanding and learning the intricacies of masterful use. Less is more. Reduce complexity, introduce laconism. As a point of reference, I’d point to Adobe and Apple. Scrivener’s manual should not be more than 200, max 300 pages.

There’s an entire industry built around third-party documentation for Adobe products. That suggests that perhaps their documentation should be more comprehensive, not that Scrivener’s should be less so.

Katherine

You missed my point. 3party documentation of Adobe and Apple products argument is irrelevant. Have you read their official manuals? I assume you have. Too wordy texts obfuscate not facilitate comprehension: you should be aware of the fact of the human psychology that on average only a tiny part of verbal and textual information enters the human mind and stays there because it’s of the limited capacity. The more you pour the more it spills. The examples of good and bad manual writing:

Good

Adobe Illustrator

Apple Aperture

Bad

A manual is not a piece of fiction. More to the point, down to earth. I understand that writers tend to be talkative, but where it considers technical aspects it’s superfluous.

Also. The description of UI traditionally goes before the main body of a manual, not as an appendix. A user gains the general view of the user interface before going to the exploration of its facets at length. That’s logical and for a reason.

I consider Scrivener’s manual to be one of the best around, so I guess it’s a matter of perspective. I love the fact that it is nuanced and loaded with info. Some of the other software I use has frustratingly poor documentation. I’m glad Scrivener errs on the side of too much info.

I should note that I’ve never read it cover to cover! Only dipped into sections as needed.

If I am not myself mistaken, this is not the case.

Have you read the text? And understood the content?
Your example is a very good example of the opposite of what you try to prove. It’s actually very smart to explain the design philosophy and the purpose of the various parts of Scrivener, not just the keyboard shortcuts or menu commands.
If you know exactly what you want to do and just want to know the correct commands, use the Help function and search for it. But if you don’t really understand some part of Scrivener, read the manual!

It is not. – Katherine

Whether you use Scrivener 2 (as in your screenshot) or 3, make sure to read Chapter 2, About This Manual, to understand the manual’s logic and its comprehensive purpose as companion to the Interactive Tutorial.

Spend some time with the material and ignore your subjective desires of placement. Maybe you’d do it all differently, fair enough. I don’t think it stands you in good stead to criticize the accomplishment that it objectively is by calling it a bad manual.

Yes, I’m biased. I’ve read them. I have admiration for the jobs well-done. Hat off to, Ioa.

Particularly because Scrivener’s design reflects a completely different approach from most word processing tools. People often struggle because they attempt to treat Scrivener like a less expensive version of Word. It’s not. It’s a completely different tool, and the manual explains how and why it works the way it does.

FWIW, I’ve never read the manual cover to cover, and don’t think most users should even attempt to do so. Go through the Tutorial, spend enough time with the manual to figure out how it’s organized, and then get back to writing.

Katherine

The purpose of this forum is to give feedback not sing praises which is what I did. When I get down to learning software the last thing I want is to “study the philosophy of the manual”: all I need is clear, short instructions pertaining to each use case. Ideally, one wouldn’t need a manual at all but if it’s impossible to do without it then it’d better if it was more user-friendly.
To the member of Scrivener support team who said that the manual is not meant to be read cover to cover why then include it in the first place? Instead of agreeing to the validity of my point and making it better we’re now arguing that either its philosophy is great and it requires additional brainwork on part of the user or “it’s just not conventional word processor” although I made my best to show that’s not the case. Scrivener is definitely not the most complex application it’s its manual that is. I read every manual of every application I use in order to get manufacturer’s perspective and avoid unnecessary ambiguity in the future. Scrivener’s manual, whoever wrote it, has the most problematic structure and language I ever encountered. I call to the authors for avoiding words inflation in favour of the simplicity of writing.

An encyclopedia isn’t meant to be read cover to cover, so why do we bother with them?

You gave your feedback, you were given several reasons why the L&L team don’t agree. Obviously, they don’t agree. Why keep tilting at windmills?

While I did give praise within my feedback, at no point did I suggest that all feedback should be in that form. See the sentence immediately prior to the one that has been cutout and used as a quote of me. Agreement isn’t a requirement for posting Feedback, only politeness is.

In general, other than my closing sentence of praise, my post in its entire context was in the spirit of suggestion. It wasn’t asked for, but this is a public forum. It wasn’t meant to be an attack or attempt to squelch feedback.

As an afterthought, I should’ve foreseen that including my praise of the manual within the post could promote a “one against the other” impression. I should’ve omitted it or better isolated it from the suggestion. I apologize.

It’s just my two cents, but I find the idea of a design philosophy in the manual and a style that is personal and sometimes wordy, better than a “just the facts” approach. The Help menu give the facts, the manuals an inviting read that gives me the facts.

I’d much rather my students wrote the latter than the former. In Scrivener’s case, if one reads patiently, it is clearer when it is more verbose. I enjoy reading it. When was the last time that happened to anyone?

And yet you’re complaining about the detailed discussion of the manufacturer’s perspective in the Scrivener manual. Ok.

Katherine

A manual isn’t an encyclopedia, it’s a guide on how to use the app. I replied because I was replied. It doesn’t matter whether L&L agree or not. They should take notice of what their users want and act accordingly.

You cited a wrong sentence to support a very inaccurate conclusion of yours. I talked about the style. And yes, I complained because I find “manufacturer’s perspective” flawed as opposed to that of Adobe and Apple. I made specific arguments why, I referenced other examples. And so?
At this point I can’t add anything new and I don’t want to utter the same repetitive lines that themselves are self-contained and substantiated.

Even if you actually believe that broken philosophy, with just the briefest glance at the participation numbers, that is exactly what they are doing in this case.

Indeed, I appreciate all feedback on the manual. Can it be improved? Always. In fact the area you highlighted in a screenshot has been trimmed and refactored quite a bit in the newer revisions (you’re looking at something that is many years old now). The almost exclusively descriptive nature of the first revision was a thing that topped the list in negative criticism, and the new revision breaks out much of the paragraph format into subsections and lists.

There is still quite a bit of design discussion, particularly in areas that we know to be speed bumps in the learning process, but it is now easier to skip over these sections if you are familiar with the topic, and browse quickly to the more pragmatic instructions on what X, Y and Z do.

Unfortunately this change in format (along with a more expansive typesetting style and design) resulted in a physically longer manual! I recall a while back I tried typesetting it using a more traditional stylesheet, with roughly the same number of screenshots the old manual had, and despite v3’s massive feature set expansion over v2, it only came out a bit longer than the v2 manual. It was not terribly out of step with other PDF manuals for complex and broad software, like Nisus Writer Pro, BBEdit and others.

So appearances aside, steep cuts were obviously made—and as such I’ve come to empathise with why some companies do not provide PDFs and put all documentation into thousands of isolated and interlinked HTML containers: that way you never really know how much is there!

That said, and as devinganger hints at, we do receive primarily positive feedback on the manual as a whole, overwhelmingly so. It always surprises me how many people write in telling us they’ve read it from start to finish out of pure enjoyment. There are always going to be those that prefer another style of course (some quite loudly so—there are always going to be those One Star Reviews for any written work). Personally, I find Apple and Adobe’s documentation to be rather tedious, even wasteful in that often it simply restates what the very interface itself has to say. My favourite manuals have always been those that talk not only about what a feature does, but why it works that way, and how it can integrate with other features, along with our usage of those features.

Ha, Ioa that is exactly my view of the Adobe manuals; I’ve used Illustrator for years and I want more detail not just a facile set of steps I can easily surmise from looking at the UI itself. I really dislike their manual style…