Horrible Documentation

The program may be great but the documentation is appallingly bad. Every time I have searched for how to do something, it is just not there. How to you enter a slur? it’s not in the documentation. How do you delete a bar? It’s not in the documentation. How do you add a composer? It’s not in the documentation. I have seen MUCH better documentation on $20 programs. PLEASE provide a well indexed documentation system that can also be accessed offline!

There is discussion elsewhere in this forum about Dorico documentation. It’s being improved, it is online and various users are helping. You can be confident suggestions for improving it will be taken into account. Good luck!

Entering a slur is covered in one of the seven YouTube Dorico orientation videos.
https://www.youtube.com/watch?v=xiavwTdRkNU
That doesn’t excuse the current state of the documentation (which is scattered where it exists at all), but the videos are a source of help and worth a look.

I agree,some serious documentation of Dorico,even in its current state,should have been top priority.We are not talking about writing code or adding features here but how to use the program as it is.

Just as an example,for some days i was wondering where the hell other vst(3) instruments except HalionSonic could be loaded from.My obvious choice would be something like Setup,Preferences.Players panel,etc.No-it was in Play mode,on the right,clicking on the dropdown menu.This is mentioned in the online Help menu but not easy to figure out where exactly, because it’s not written in a functional & usable way. Let’s not talk about how to load vsti only (like Kontakt),it’s a nightmare.

Come on Dorico team ,we can’t keep on searching of the obvious answer in a forum!

In my case, I only had a few difficulties entering a score, because I was a long time user of Sibelius and was familiar with a lot of the concepts. The First Steps manual helped a lot, but it has not been updated for Dorico 4.

My main problem is in trying to figure out how to use the new Play Mode. Why is it that all the other modes are documented in the manual, but Play Mode is not. It isn’t even listed in the index or table of contents!

Also it would be nice if the full manual had a bit more of a hierarchical organization. It is so long that it is difficult to find things. Even browsing through the index is frustrating because of its length.

It has been documented in the forum. Play mode is going to evolve quite significantly in the next weeks or months and it’s useless to waste time on writing something eager to be outdated so quickly, especially with a small team as this is.

1 Like

Yes Play mode isn’t yet included in the v4 manual, it will be reinstated as soon as possible but that won’t be for a little while. I wrote up a little overview of the manual update for v4 here:

In terms of hierarchical organization – have you got some examples that stand out in particular? In the PDF, the continuous stream of pages doesn’t highlight the structure as well as perhaps the list of contents does in the webhelp version. But depending on your browser, you should be able to see a TOC on the left of the PDF.

For example, each mode has its own separate chapter that covers the key bits of UI in that mode and then sections of things that you can (generally) only do in that mode.

Then there are other sections, primarily the Notation reference at the end which has a separate chapter for each type of notation, where you’ll find information specifically relating to that notation. Another good chapter is Page formatting, that initially goes through the different steps most commonly needed for part & score preparation, with more detailed information and further details in sub-chapters at the end of the chapter.

Finally, on the webhelp simply searching relevant words and phrases should bring up fairly good results. In addition to the body text and index etc, the webhelp benefits from additional keywords that I’ve added based on how users have asked questions in the past.

1 Like

First thanks for the prompt replies!

As for the browser I use, I don’t use a browser to read the manual. I have downloaded the manual and use Apple’s Preview program, which is essentially a pdf viewer. So, no, I only see the Table of Contents (TOC) in the first few pages of the manual. Frankly, I use the index far more than the TOC.

When I mentioned hierarchy, I was referring to the following. Looking at the Table of Contents, you will see every bold-face entry seems to be a chapter heading, except a few. “10 New features”, has no sub-entries. Similarly for “769 Notation reference”. Oddly, it is followed by “770 Introduction”, without any indication in the TOC what is being introduced. I just think using different font sizes, bold, etc., along with proper outlining form might improve the index. Of course anything that can be done to minimize the amount of jumping 500 pages at a time would also be useful. In particular, I think everything related to Setup Mode should be in one clearly marked section of the index. Everything related to Write Mode should follow it in another clearly marked section. Etc. for the other modes.

You rightly point out that each mode has a chapter, but once you read the TOC down beyond “556 Print mode” this clear organization disappears. “578 Page formatting” might seem to reasonably follow print mode, but why is it followed by “658 Properties” and then “663 Library”. It’s just that I think it all could be a bit clearer. Perhaps adding chapter numbers (only in the index and on the first pages of each chapter) might help. I see where the Notation reference begins, but where does it end? At the Glossary?

On a project of this size, documentation is obviously important (and a lot of work to write). You guys have done a magnificent job. In the long run, I am confident I will only be using Dorico.

For viewing the PDF locally, I tend to use Adobe Acrobat, as that has an option to show the table of contents on the left which makes navigation easier. We now include headings for each letter in the index in our outputs, making it really easy to jump to where entries beginning with S start, for example.

Without wanting to get too in-the-weeds about the hows and whys of the manual, here are some bits of info in case it’s helpful to you when using the docuementation.

The way we write and generate documentation means that overarching rules govern the output. The boldness of titles in the TOC reflect topic depth, primarily. The Notation reference is a slight anomaly due to how it’s structured internally, but there the “Introduction” page is the introduction to the Notation reference, and each notation’s chapter follows on.

The New features page has no sub-entries because it has no sub-topics: click the link and have a look, it’s basically just a list of new features added in the specified version, with links to take you to where each feature is documented in the manual so you can read more about them.

The non-mode chapters contain information that is either not bound to any particular mode, or whose content semantically fits with other related topics, like the Page formatting chapter. They come after the mode chapters but before the Notation reference because that seemed to be the best place for them: not disrupting the flow of the modes, but not before them with the other introduction-y chapters (it didn’t seem sensible to describe how to enable condensing before going through how to add players, for instance). Still, their contents should be fairly easy to discern from their titles: the Library chapter is about Dorico’s library (various default options and customizable notations, typically operating at a high level, e.g. per-flow, -layout or -project); the Properties chapter is about Properties, given that these are accessible in both Write and Engrave modes (following “default settings” with local-instance overrides); the Page formatting chapter includes key information about how to format parts, including changing the page size and margins.

Suffice to say, I do think quite carefully about not only what to write, but where to put it and keep that under constant review :wink:

We considered how best to utilise the index and decided against essentially replicating the TOC. Instead, the index is focused on terms, actions etc - including synonyms we don’t generally use, so you get a signpost to the term we do use. Index entries serve (hopefully) any likely train of thought: if you think “dynamics - what can I do with those?” the subentries for “dynamics” will give you a whole raft of options; if you think “I want to move dynamics” you should find relevant entries under “moving > dynamics”, etc.

Our intention with the documentation is that it offers multiple possible routes to you getting to the information you want: the TOC, the index, related links, keywords for online searches are all available.

If you like using the TOC and hierarchy to navigate the manual, I really would recommend trying a PDF viewer that lets you keep the TOC open and expand chapters/topics with sub-topics, it really helps with the geography, I find.

1 Like

The Mac Preview app does indeed let you view the TOC in the sidebar.

Since I am the person who started this post about 1 week after Dorico was initially released, I would like to add some new thoughts. The Dorico documentation has improved TREMENDOUSLY! Thank you so much @Lillie_Harris for your amazing work.

For searching the online version, I would implore everyone to read the search tips before attempting any searches. The one thing I still find mildly annoying is that if you (for example) start to type audio into the search box, you will get a list of suggestions. If you then pick one of the suggestions (for example export audio dialog) you will get a set of results that includes every reference to any of those words. Most times the most relevant results do appear at the top of the list but not always. It would be wonderful if when selecting one of the suggested phrases, the search would be done as if one had entered the phrase with quotation marks so that you don’t get over 900 irrelevant results.

Once again, thanks for the great work. Bob.

4 Likes

Awesome. :wink: