If Scrivener is open to constructive criticism, then can I advise you to take a long, hard look at your manual. Speaking as someone who operates over many disciplines and has to regularly reference technical manuals, I find it absolutely useless, and that is not hyperbole!
There are excellent manuals out there. Scrivener is a fairly complex piece of software, but that does not license the manual to be more complex than the software. The format is good, the grammar is good, it seems logical, but pick a paragraph at random and you’ll find it hard to understand. I think the problem is that most people read a manual with a view to doing something and the manual seems directed at understanding Scrivener.
It’s important to remember, though, that the manual is only part of a comprehensive set of support resources, including a variety of tutorials. Often, people turn to the manual because they need to understand how something works in order to customize it to their requirements. Most users will open the manual rarely, if at all.
Intrigued by @thecamster 's complaint, I randomly picked some paragraphs from the manual. I found them all to be difficult to understand, because almost all of them were exceptionally long by modern editing standards.
A general rule of thumb in editing the written word is no sentence over 25 words. The sentences in the Scrivener manual were as long as 56 words.
Here is an example:
This is most useful when the method you used to arrive at the current document did not involve clicking in the binder (such as using the history navigation buttons or using a link), or if you are currently viewing a col- lection and wish to find where the file is actually located in your project outline.
If L&L wants to improve the utility of the manual, perhaps they should look to having an editor go through it. They could break up the long sentences and make the manual easier to understand.
I opened it yesterday while trying to help a user with list formatting. Below are the results of a search for “list”, nearly all of it not about lists. The question was about indenting to new levels, and the closest thing seemed to be verbiage about increasing/decreasing tab indents, in an appendix.
I didn’t find that by searching. I randomly remembered “A.10” from a recent post on the forum. I still don’t know if what I found is relevant to the question.
I agree, the paragraphs are exceptionally long, which throws one a little. But the rot goes deeper. Even when you have a fairly good idea of what you are looking for and the context around it, you struggle to decipher the prose. It has been a unique experience for me - I read a lot of technical stuff, some of it highly abstruse - but I have never been so discombobulated.
YES! That has been my experience. Look for information on something you are trying to do and you are led into the brambles. I have had to find all my answers on the internet.
FWIW, the manual’s Table of Contents is a vastly better way to find things than the search function. Probably because we wrote the ToC, while the search function is dependent on your PDF reader.
For basic formatting specifically: All formatting commands can be found on the Format menu, which largely duplicates functions available in most word processors. A complete list of all menu commands can be found in Appendix A.
To clarify, the problem I see is that many of the paragraphs are a single, long sentence in excess of 25 words. Long paragraphs made of short sentences are usually fairly easy to understand.
Long single sentences become obscure as they pass 20 words. 56 words (like my example) are pretty indecipherable.
Opened the Scrivener manual after gasping at the page count and after reading random sections for a bit, knew that the author(s) had built some logic into its organization. I had to find out what it was so went to the ToC and found the appropriately titled second chapter––About This Manual. A current excerpt (similar to or the same as before):
Although it will endeavour to explain features in depth, the Scrivener User Manual is intended as an exhaustive reference, rather than a training tool. The best way to kickstart your use of the software is to take the Interactive Tutorial, located in the Help menu.
If you want to use the thing, Chapter 2 is a good starting point.
Another excerpt:
2.2 Finding Things in this Manual
This pdf has been birthed within the age of digital documentation, and a proper index has never been compiled for it. Despite this, in practice you should have little difficulty in locating the topic you are interested in. Modern pdf reader software features excellent searching capabilities; most things can be discovered merely by searching for the proper names of things as labelled in menus, buttons or dialogue boxes.
Alternatively, the appendices have been written to be used as a sort of topical index. If you have a question about a particular menu command, for instance, you can find it in the appendix, Menus & Keyboard Shortcuts (Appendix A), or Preferences (Appendix B). Throughout the manual itself, cross-references to more thorough descriptions of the feature will be provided. When all else fails, the table of contents has been provided at the beginning of the pdf to get you roughly where you need to go, and larger chapters will have more detailed con- tents provided. Additionally, if you are using a pdf reader with a contents sidebar feature you will find that to be a much more detailed table of contents than the one in the front of the book.
Two things I noted from @drmajorbob negative experience with the manual, and this IS NOT a personal criticism of him IT IS an attempt to help, were that
To target a term as generic as the word list is a waste of time in a word processing manual. Add context such as bullet, format and the like. Combine that with looking at the main ToC, a Section ToC and /or Appendix A/B.
On finding a Documents Template explanation: The excerpt which was posted came from Appendix F What’s New, which is why it was worded (previously, etc.) the way it was. Using Document Templates as a search term would likely give you joy. But again if needed, combine that with ToCs, etc. There’s an entire subsection in the manual––7.5 Document Templates.
It’s quite possible that someone new to Scrivener’s terminology would not know (or be confused) that there were Project and Document templates. Finding info in the manual is not impossible under those circumstances but, of course, more difficult. Which brings us back again to the advice given in the quote I opened with––do and redo the Tutorial.
I don’t know how much of an issue sentence length is. A 60 word sentence doesn’t bother me, but that’s just me. And using the manual and tutorial as they were intended to be used has profited me. Both are high quality. Can either or both be improved? Of course. L&L accepts specific, polite suggestions. Doesn’t necessarily mean they’ll agree but they might. A tremendous amount of work went into producing the manual (and other resources). It’s quite an accomplishment. Something for a guest to keep in mind before making a suggestion.
[EDIT–forgot to say manual references came from Mac manual]
I don’t need help, personally. I knew the answer to document templates and never needed the answer to lists. If I did need it, my process generally starts with experimentation, and for lists, it took me about 5 seconds to create a list and find the answer in one try. Before reading on, I challenge you to find it in the manual.
(I need to get back to the user I tried to help before. I should have experimented instead of looking in the manual.)
I later searched for “bullet” with more luck (and still didn’t get an answer), but you generally cannot add context when searching a PDF. Scrivener has bullet lists, but a search for bullet list finds nothing.
The good news is that there’s a Scrivener project version of the manual, and it does contain the phrase bullet list, oddly enough. (Why doesn’t the pdf, I wonder?)
The bad news is that the one location where it’s found is pretty much useless:
The good news is that we have more ways to search the project version of the menu, and there are 7 documents in it that contain all three of the words bullet, list, and tab.
The bad news is that none of those documents gives the answer I found with basic, instinctual experimentation, namely that tab is the way to indent a list to a new level. I know that because I searched for tab in the 7 matching documents, looked at every mention, and didn’t find the answer.
More bad news: A search for list and tab only (without bullet), yields 178 matching documents, one of which may (or may not) yield the answer.
Sorry, I’m not going to look at all 178 of them.
Which is far more useful than the basic Find pane’s count of hits. I’m sharing this in case there’s someone else out there who wasn’t aware this feature existed.
That said, I was unable to find the answer to the question Bob’s user had asked. I suspect the manual does not address it.
It doesn’t exist in Acrobat Reader at my machine (Mac). It has an advanced search I didn’t know about until now, but it’s not particularly advanced, certainly not as advanced as what you’ve shown us.
Thanks, though! It may come in handy someday.
No snippets here. Bummer.
I suspect it does, but I doubt I’ll ever find it there. Even if I do, guessing was a lot faster.
Oops, I do have the better search here after all. Looking at it before doing the search, I stupidly assumed I did not. The snippets don’t appear until I do the search, and I was distracted by a hunt for “all words” and other search features I’m used to in Scrivener.
The more powerful search does little or nothing to help, though.
I cut my teeth reading a lot 18th and 19th century translations of classics, and I recall that long sentences (what we might call a paragraph) seemed to be the norm. I suspect that people had better attention spans then and not subjected to so many distractions. Because of that experience long sentences don’t bother me. And I’m not shy to use them either. Not that every sentence has to be a mile long. But with punctuation it is doable.
I am not making a recommendation, just an observation.
I’d also make the observation that those classics are not technical manuals, and are not attempting to be instructional. The less-than-20/25-words-rule is within the domain of business and technical writing. Fiction is filled with authors who love impossibly long sentences.
FWIW, I actually picked a random page and counted. 231 words total, not including a four word header or a 20 word figure caption. Longest sentence 51 words, shortest 11 words, 9 sentences total for an average of 25.7 words each. (Fun trivia. The second longest sentence had 34 words, but 12 of them were the full names of two different configuration options. Abbreviating those in a manual seems unwise.)
Mostly, when folks say “average” they mean the arithmetic mean. I asked her for the median sentence length. The median is often a more useful indicator, because, as wikipedia puts it:
is not skewed by a small proportion of extremely large or small values, and therefore provides a better representation of a “typical” value.
I calculated the arithmetic mean. The median was 21 words. Since the manual is downloadable as a Scrivener project, a person with more ambition than I could calculate such statistics for the whole thing pretty easily.
