I took the time to download and read through the Scrivener 3 manual yesterday. (Available here: https://www.literatureandlatte.com/learn-and-support/user-guides

This is probably the best software manual I've seen this century. It's mammoth -- 847 pages, US letter size -- and well written. There are a lot of features you'd have a hard time discovering on your own... e.g., I didn't know Scrivener now supports automatic transclusion, and it would have taken me forever to discover the "centered outlining" mode designed to simulate single-pane outliners (Figure 8.23; section 8.3.6). Even if you're not the type to normally read software manuals, you'll probably get something out of reading this.

You would hope documentation for a writers tool would be well written.

Writing documentation for software is a bit of a demoralizing task, as you know the vast majority of people will never read it.

In fact, I have plenty of empirical evidence that show that people will not even read a one line error message (that tells them exactly what the problem is and how to fix it!). I'm sure that doesn't apply to readers of this forum though. ;0)

--
Andy Brice
http://www.hyperplan.com

The person responsible for most (probably all) of the Scrivener Manual is Ioa Petra'ka, who I think (I could be wrong) used to be an occasional contributor to this forum (and also the much-missed ATPM website). He certainly knows a great deal about Tinderbox (which originally encouraged me to try that application), as well of course as Scrivener.

I have to confess that I haven't had the time to read any of the Manual for Scrivener 3 yet, but if it's anything like the Scrivener 2 Manual - and it sounds as if it is - it's likely to be a magnificent piece of work, in terms of the scope, precision and clarity of its content, the speed of its delivery and its use of Scrivener and other pieces of technology in putting it together.

The Manual has long been one of the features that have made Scrivener worth purchasing, and, with Ioa behind it, I'm confident that this must also be true of the Manual for Scrivener 3.

(Incidentally I've always been surprised by the number of posters on the Scrivener Forum who say that they're working their way through the Manual. Good for them! But for me it's chiefly a work of reference.)

Andy Brice wrote:

You would hope documentation for a writers tool would be well written.

Writing documentation for software is a bit of a demoralizing task, as
you know the vast majority of people will never read it.

As a technical writer by trade (and I write fiction by night, I must be a masochist), I gotta say "Amen, brother."

Writing documentation for software is a bit of a demoralizing task, as you know the vast majority of people will never read it.

On the plus side, there's no way to thoroughly learn a complex program's capabilities that comes close to authoring its documentation. At least that's been my experience with writing the Help file for NoteCase Pro. (Just checked, latest draft currently at 1703 nodes; online version from last release at http://notecasepro.com/help.php .)

Chris, thanks for posting and the recommendation. I'll study the Scrivener Manual for ideas.

Best regards,

Paul E. Merrell, J.D.

Writing documentation for software is a bit of a demoralizing task, as
you know the vast majority of people will never read it.

Write API documentation, that is where people can't get enough of it.

In fact, I have plenty of empirical evidence that show that people will
not even read a one line error message (that tells them exactly what the
problem is and how to fix it!). I'm sure that doesn't apply to readers
of this forum though. ;0)

But on the other hand they will watch a 45min youtube video for learning
something they could read in 5 min.

I think the problem in the past was that documentation was very very
bad written and not fit a lot of people. If you explain in length how to move
your mouse to click some button you lost have documentation that is soon
out of date and pissed of everyone who is a little bit more experienced.
And now the later is the majority.

Dont explain menu items, explain concepts and mental models of how
data is managed and handled. People can find out how to add something
if there is a [+] button. The need to describe this level is a total failure in UX.