Feedback on Dorico documentation

Dorico
1

I want to give the Dorico tech writing team some feedback on how they could potentially increase adoption. The Dorico users manuals are terrific, but I think with some few tweaks, they could be much more useful.

The first is SEO. Usually when I want to figure out how to do something in Dorico, I search Google. Unfortunately, the way you have the documentation structured, the search results inevitably lead to out of date documentation from an older version of Dorico, even when searching explicitly for “Dorico Pro 5”. SEO is outside my area of expertise, but I know it’s possible for you to give hints to search engines, either with meta tags or through better URLs that give a better chance of your end users ending up in the correct place.

Secondly, it would be fantastic if your online documentation contained more hyperlinks, especially when telling users where to find certain features. For example, on the Beaming Page , you state the following:

There are many different accepted standards for how to present beams, so Dorico Pro offers a number of customizing options. You can find these options on the Beams page in Engraving Options.

This isn’t particularly helpful to a new user. Where is Engraving Options? Maybe click on the Engraving tab and look under the Engraving menu? That would seem logical. Nope. Now, a new user still doesn’t know to do the thing they are trying to do. They’ve got to do another search through your documentation to figure out how to access Engraving Options. If that were a hyperlink to the Engraving Options dialog page, you could save new users so much time and frustration. I’m betting there is a tool out there that could largely automate much of this, in fact.

Thank you for considering this request.

5 Likes
2

That is largely Google’s doing, not Dorico’s, since older versions of the documentation naturally have more clicks (including mistaken ones) that put it higher in the Google Queue.

(I always access the documentation through the Help menu in the Hub or from within an open copy of Dorico to make sure I find the latest information. One can of course also create a browser hotlink/tab for the most recent version.)

1 Like
3

The Engraving Options scenario is a good example of what happens to so many new users who don’t review the Getting Started materials. Dorico is not designed for users to just pick up by trying things on the screen. It requires some study to get going.

3 Likes
4

But it might be nice to have the possibility to change the version more easily?

The page tells you at the top, that you’re in the manual for Dorico 5. Maybe create a link to older/newer versions right next to it?

The same is true, if you want to change the language. You can edit the url but it’s not the nicest way to do so.

But in general, you find almost everything you want to!

5

I would still like the documenation PDFs to be downloadable/updatable via the Steinberg Download Assistant. When I download the app, I want to download the manual. When I update the app, I want to download the manual update. When I want to check for updates, I run the Download Assistant, to… you guessed it… update the app and/or download the updated manual.

It is bizarre to me that, instead, I have to google for the Steinberg Dorico documentation web page (and also check to see that I am on the right version) and then navigate to download the PDF’s manually, etc… when the Download Assistant already exists.

Often, I keep the Dorico PDF’s open in the background at all times of working on a score, to use as reference.

3 Likes
6

The link to the documentation is available via the Hub from the Learn tab.

1 Like
7

Dorico App’s button/menu to open the documentation is simply a bookmark which opens a web browser: still requires downloading the PDFs manually, without a ready way of knowing if there was a documentation update from any previously downloaded version, just that it’s “the latest”.

8

There is no PDF manual. It is all on line. Not sure how much memory it would take if we were able to download the entire web structure onto a personal computer. I am happy to make do with the current structure.

9

Thanks for your feedback.

We’re well aware of this, and would like it to be easier/more obvious to switch between manual versions when you’re on the page. This could well be a future improvement across all Steinberg manuals.

Prioritizing one version over all previous ones in terms of external search engines is a little tricky, as there’s no guarantee that the person searching has the latest version of the software, and therefore should consult the latest version of the manual. A more robust filtering/switching system on Steinberg.help should solve this.

These days, it certainly is the case that if something is mentioned in a topic, there’ll be a link to further information about that thing at the end. This is not automated; I have to add links manually. I do try to order links with something resembling logic: roughly the order in which other things are referenced in the topic, or the most obviously relevant at the top, etc.

Older parts of the documentation, and parts I haven’t had a reason to revisit lately, might well suffer from insufficient links. For the inconvenience in the meantime, I can only apologize.

However, I can’t help but notice that on the “Beaming” page you’ve picked out, there are in fact direct links to both Engraving Options and Notation Options at the bottom of the page (spoiler: this is where all links go; hyperlinks within the body of the text have been requested before, but this is not currently how links are handled in Steinberg manuals).

Similarly, take a nearby topic that involves the Properties panel: Changing the thickness of beams. The prerequisites involve the lower zone being visible, the Properties panel being the current panel shown there, the property scope being set to Locally or Globally as appropriate, and Graphic Editing being selected in the Engrave toolbox (if you are in Engrave mode). Scroll down to the bottom of the page, and you’ll find links to all of these things. As ideally there should be on every task that involves doing something with the Properties panel (it’s somewhere in the region of 500, I think), although I think some might not have the full complement of links.

If you come across a page in the latest manual that genuinely does not have a link to an obviously relevant topic, please let me know so I can add it. (Barring any severe errors that need correcting, I generally don’t make amendments for earlier versions’ manuals.)

6 Likes
10

There is a PDF manual. We publish the same documentation content as both a PDF and online webhelp simultaneously.

3 Likes
11

In general, the date shown on p2 in the PDF reflects when the PDF was last published. If it’s different to the version you have downloaded locally, then it’s been updated. Having said that, for very minor corrections etc, I may not always update this date (which needs to be done manually) but as a rule of thumb, that date should be quite helpful.

12

@Lillie_Harris
Of course there is a PDF manual. Must have been a Senior Moment on my part. :grimacing:

13

44.5 Mb.

Screen Shot 2023-06-03 at 12.16.57 PM
Screen Shot 2023-06-03 at 12.16.57 PM622Ă—802 63.5 KB

14

The problem I find is that the links are below the “first screen” forcing users to scroll down and then go through a sometimes long list, that is in no obvious order (certainly not alphabetic) in order to find a link that might help them. I think many users not finding their answer on that first screen of text will go back to the search field or give up. I’ve also found myself clicking on some of those links only to find that none of them helped me solve the problem I was having. As mentioned by me and others is that if you don’t use the right search term or look in the right category you’re unlikely to find it. (Why inputting real-time midi settings/quantization is in the output (play) section of the preferences is one that still confuses me).

15

I don’t know what you mean by “first screen” - I’ve always found the links at the bottom of the page - a single screen. Are you just saying you take issue with needing to look further down the page? That seems like maybe a low screen resolution accommodation issue more than anything else, which as was mentioned earlier - they’re part of the Steinberg company and have to follow Steinberg’s web formatting rules.

Regarding midi settings, I think the issue is that you’re thinking of the Play section as “output” rather than “midi section”. I don’t view Play as being an “output” mode, it’s the midi manipulation mode - which makes perfect sense to have midi input settings there.

1 Like
16

Some people want a link to every thing mentioned on a topic, other people want a short list. For every link that one person finds superfluous, another person rails at its absence. I try to find a balance, but as always, if you have some particularly egregious examples to share, let me know for consideration.

As I said above

–

Sorry to hear that: if you can give me some concrete examples, I can make amendments if necessary.

I don’t doubt that this can be the case, but I spend not inconsiderable time doing my best to accommodate a wide variety of terms and approaches. Sorry to be a broken record, but if you share some examples of what you searched for but couldn’t easily find an answer to, I can review the relevant topics’ metadata.

For the structuring of options within the app itself, that’s outside my control. But helping you find information about and directions to it within the manual, that I can help with.

2 Likes
17

Anyone who complains about the Dorico documentation needs to understand that Lillie is required to apply a house style that is imposed by Steinberg on documentation for all its products. I don’t know who determined the house style itself, but it is enforced by company administration and it is very unlikely to be changed. For what it’s worth I think this house style is obtuse and results in a worse documentation product than would otherwise be the case. But it is what Lillie has to work with. As I’ve said many times before, given the strictures imposed upon her, Lillie does hero’s work writing the Dorico documentation, and I doubt anyone could do a better job given the circumstances.

10 Likes
18

And, like Daniel and Ulf, Lille is one of the most available members of the Development Team here, helping users and constantly asking for example search terms that went astray in order for her to improve the site’s search results.

2 Likes
19

Mark, I’ve used Dorico since V1. I don’t do copying jobs since switching to Dorico from Sibelius. Honestly, Dorico does a good enough job for my needs (usually a single-player remote recording session) that I only go into Engraving Mode maybe once a year, and I forget where it is EVERY DAMN TIME. I can guarantee that Dorico has a big market of people just like me. It’s a far better tool for us bull-in-a-China-shop composers than the competition.

Also, I gave concrete, actionable feedback on their documentation to make it easier. Saying, “It’s hard because it’s designed that way,” is a pretty unhelpful response, to be honest.

20

Yes, it’s Google’s doing, but Steinberg could easily adapt. That’s what I’m proposing.

Again, this is not my area of expertise, but here’s a solution that would admittedly take some webdev development time:

All five versions could link to the same place that never changes. Then, you select the version once, the first time you enter the help section, and that selection is maintained by a cookie or login functionality. You would always get the correct version of the documentation, except when you updated Dorico or were going back and forth between multiple versions of Dorico. Steinberg would probably serve the search engines and other bots the most recent manual via a robots.txt and appropriate redirects.

2 Likes