Scrivener's manual - skim the fat

[Dreischock]

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.

[kewms]

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

[Dreischock]

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

Illustrator.png (151.38 KiB) Viewed 1124 times

Illustrator 2.png (91.78 KiB) Viewed 1124 times

Apple Aperture

Aperture-2.png (220.28 KiB) Viewed 1124 times

[Dreischock]

Bad

Scrivener.png (1016.56 KiB) Viewed 1124 times

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.

[Kinsey]

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.

[mbbntu]

the author (who is also the developer)

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

[lunk]

Bad

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!

[kewms]

the author (who is also the developer)

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

It is not. -- Katherine

[scshrugged]

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.

[kewms]

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.

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

[Dreischock]

I don't think it stands you in good stead to criticize the accomplishment that it objectively is by calling it a bad manual.

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.

[devinganger]

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?

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?

[scshrugged]

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.

[jcarman]

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?

[kewms]

I read every manual of every application I use in order to get manufacturer's perspective and avoid unnecessary ambiguity in the future.

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

Katherine