Scrivener's manual - skim the fat

Dr
Dreischock
Posts: 8
Joined: Wed Nov 06, 2019 8:37 pm
Platform: Mac

Sun Feb 02, 2020 4:07 pm Post

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.

User avatar
kewms
Posts: 6434
Joined: Fri Feb 02, 2007 5:22 pm
Platform: Mac

Sun Feb 02, 2020 6:04 pm Post

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
Scrivener Support Team

Dr
Dreischock
Posts: 8
Joined: Wed Nov 06, 2019 8:37 pm
Platform: Mac

Sun Feb 02, 2020 6:45 pm Post

kewms wrote: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
Illustrator.png (151.38 KiB) Viewed 1084 times
Illustrator 2.png
Illustrator 2.png (91.78 KiB) Viewed 1084 times



Apple Aperture



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

Dr
Dreischock
Posts: 8
Joined: Wed Nov 06, 2019 8:37 pm
Platform: Mac

Sun Feb 02, 2020 6:46 pm Post

Bad

Scrivener.png
Scrivener.png (1016.56 KiB) Viewed 1084 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.

Ki
Kinsey
Posts: 418
Joined: Mon Apr 09, 2012 6:06 pm
Platform: Mac + Windows

Sun Feb 02, 2020 9:18 pm Post

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.

mb
mbbntu
Posts: 1267
Joined: Wed Aug 01, 2007 9:44 am
Platform: Mac + iOS
Location: Cambridge, UK.

Sun Feb 02, 2020 10:00 pm Post

Dreischock wrote:the author (who is also the developer)


If I am not myself mistaken, this is not the case.
You should judge people not by how close they get to the top, but by how far they have come from the bottom. Some people have a mountain to climb just to get to the place where others start out. (Me, 2010)

User avatar
lunk
Posts: 4193
Joined: Wed Aug 21, 2013 4:24 pm
Platform: Mac + iOS
Location: Sweden 64° N

Sun Feb 02, 2020 10:11 pm Post

Dreischock wrote: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!
I am a user, writing non-fiction and science, using:
* Mac Scrivener 3 on a Macbook 12”, MacBook Pro 13”, and iMac 27”, running different OS.
* iOS Scrivener 1 on an iPhone 11 Pro, iPad Air 9.7”, and iPad Pro 12.9”, all running the latest iOS

User avatar
kewms
Posts: 6434
Joined: Fri Feb 02, 2007 5:22 pm
Platform: Mac

Mon Feb 03, 2020 12:04 am Post

mbbntu wrote:
Dreischock wrote:the author (who is also the developer)


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


It is not. -- Katherine
Scrivener Support Team

sc
scshrugged
Posts: 519
Joined: Wed Feb 10, 2016 6:55 pm
Platform: Mac + iOS

Mon Feb 03, 2020 12:49 am Post

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.
I'm a Scrivener user, not an L&L employee.

User avatar
kewms
Posts: 6434
Joined: Fri Feb 02, 2007 5:22 pm
Platform: Mac

Mon Feb 03, 2020 2:22 am Post

lunk wrote: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
Scrivener Support Team

Dr
Dreischock
Posts: 8
Joined: Wed Nov 06, 2019 8:37 pm
Platform: Mac

Mon Feb 03, 2020 6:55 am Post

scshrugged wrote: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.

User avatar
devinganger
Posts: 2112
Joined: Sat Nov 06, 2010 1:55 pm
Platform: Mac, Win + iOS
Location: Monroe, WA 98272 (CN97au)
Contact:

Mon Feb 03, 2020 10:31 am Post

Dreischock wrote: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?
--
Devin L. Ganger, WA7DLG
Not a L&L employee; opinions are those of my cat
Life has a way of moving you past wants and hopes

sc
scshrugged
Posts: 519
Joined: Wed Feb 10, 2016 6:55 pm
Platform: Mac + iOS

Mon Feb 03, 2020 11:31 am Post

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.
I'm a Scrivener user, not an L&L employee.

jc
jcarman
Posts: 147
Joined: Sun Nov 01, 2009 6:28 pm

Mon Feb 03, 2020 7:06 pm Post

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?

User avatar
kewms
Posts: 6434
Joined: Fri Feb 02, 2007 5:22 pm
Platform: Mac

Mon Feb 03, 2020 7:14 pm Post

Dreischock wrote: 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
Scrivener Support Team