Manual annoyances

This is not about style. It is about effective communication of vital information.
I know there is a separate guide but you have a manual that hasn’t properly integrated the two arms which could also be done through some hyperlinking.

I think Dorico is becoming a very fine programme but it is issues like this that will continue to reduce its effectiveness among some users. It’s a commercial imperative as much as a pedagogical one to create the best solution or provide alternative solutions to allow for the greatest productivity return.

On the contrary, I thought the explanations pretty good. The idea of outlaying a task as a procedure and what the expected result should be was the sort of thing I’d expect to see in a program spec.
Admittedly there were omissions - and I didn’t expect something as complex as notation software to detail every avenue to get out of trouble but as a newcomer to such software I find that most times I call up help I get a definitive answer.
It’s a huge manual…but it has to cover a huge amount of procedures.

It may be ‘huge’ but that is no excuse for leaving out vital information on the topic at hand.
Complex software? I started in the 1980s on Score whose manuals were as comprehensive although didn’t spend as much time on the philosophical or editorial because it was the purvue of music publishing experts. In that context everything was (and is) based on understanding hundreds of parameters and key codes. The manuals did what was expected of them being models of clarity and integration.

I don’t understand why there is a need to be defensive about the positive qualities of the Dorico manuals. I am suggesting an improvement. You can take it or leave it. Either approach has it’s implications.

At least in my SCORE 3 manual, the Index is just page numbers not keystrokes. The SCORE 3 manual reads more like Lillie’s First Steps guide rather than a comprehensive manual. If you haven’t checked out that link, you may prefer it to the online documentation. SCORE’s manual walks you through how to do certain things and shows you the keystrokes as below:

I’m not sure how that’s any better than this:

In fact, with the added visuals for each command and step, I find Dorico’s First Steps guide much more clear than SCORE’s. How exactly do you find SCORE’s guide preferable here?

Your example is a good one. Such is just not consistently the case. There are many pages without reference to a single keystroke where such information would be the very solution one would be expecting.
In checking the Score 3 Reference Manual - not the Users Guide.
The layout of information and thus effectiveness is what I (not everyone) would wish for.
The Index most definitely does point you in the right direction to know the parameter, keystroke or operation needed for any aspect of the programme.
The Index of Letter Commands (also at the back of the Reference Guide) is self explanatory.
Again, I don’t see this as a reason to be defensive. It’s simply that what is good can be even better.
(Cross stave beaming and note/stave displacement is an area close to my heart - being a harpist).

I would be very interested (and indeed grateful) if you have links to specific examples in the Dorico 3.5 (the latest) Operation Manual where key commands are missing in the tasks for operations that have a default key command. There are a decent number of tasks that only involve a menu option by default, but tasks for these should ideally have a tip at the end about how to assign a custom key command should you so wish.

If you mean more that where possible actions are mentioned in passing in a topic that’s not primarily about that operation, the key command isn’t included, then I take the point but at the moment that is deliberate: we try to keep information categorized and restricted to their dedicated pages as much as possible. It both keeps boundaries clear and helps up maintain documentation across multiple product versions and for each update. But that said, if you have some specific examples (that I can more easily investigate) where you’d really expect or benefit from the key command being shown, I’d be happy to hear that to take into consideration.

Your figured bass page is germaine.
It would have been helpful to have the line of key strokes underneath the example. And a mention about the figured bass options so that one would end up with the same result.
I certainly wouldn’t expect tangential issues to be explained in any way that detracts from the main point of the page.

Ah, right, I was looking in the Users Guide.

In general I agree with you regarding the Reference Manual. It is very clear, presents all the P values possible, and contains little extraneous or editorial information, allowing users to get the information they need quickly. Dorico’s equivalent of the “Index of Letter Commands” is Preferences/Keycommands/Print Summary. An advantage Dorico has here is that this will contain all of your custom Keycommands too. One of the features I like best about Dorico is the ability for users to modify and create custom keycommands to suit individual workflows. Summarizing all the commands this way allows all the user-configured keycommands to be included too.

Right, so you would like to see essentially instructions for how to recreate the figured bass in the example screenshot included on that page? That’s an interesting thought, I’ll make a note, although I’m not sure that’s how we would approach something like that. Additional tutorials/walkthroughs could be a possibility though.

If you take a look at the reference page specifically for the figured bass popover (which covers the things you can enter into that popover to achieve different results), you’ll hopefully see why we segment this information. Some popovers only have a few possible entries, but others - like figured bass - are somewhat complex. This is why we segment: all the information about “things you can enter into the popover” should be findable on the page about that popover. Each popover has its own page, where there is a screenshot confirming what it looks like, a bullet point list of how to access it, and table(s) of popover entries.

The benefit of Steinberg manuals being segmented in this way (according to information type and content) is that it’s better suited to online usage, which is increasingly how users access the manuals. Relevant keywords for specific pages can be embedded in the metadata, and online searches can get you directly to the part of the manual that’s relevant. It’s a different writing style to other, more paragraph-based manuals, but I can assure you that my colleagues in the manuals team are dedicated and experienced in the world of user documentation and we take our job seriously. There are good reasons for why we do things the way we do them, although of course we’re always listening to feedback and exploring other possibilities.

Clearly there should be automation advantages in a program that isn’t 35 years old (in DOS). Notwithstanding its lack of personalised keystrokes, Score’s ability to create surprisingly user-friendly tailor made macros extended its power dramatically in much the same way but always better than Sibelius’s attempt through Manuscript/plugins.

I understand the idea of segmentation but the figured bass example is but one of many where the user needs that connextion.
It’s what turns theory into practice.
Talking about something without programme integration is an issue of data fragmentation.
A digital medium may appear to be different but fundamentally each screen is a page or part thereof. I’m not easily convinced that because something is newer it is automatically and paradigmatically different.
This is what you do - this is how you do it.
Your professionalism has never been in doubt.

I think one major difference between the SCORE and Dorico documentation involves the target audience. SCORE’s target audience is/was music engravers. Dorico’s includes students, amateur and professional musicians, teachers, musicians used to working with MIDI and DAWs, and yes also music engravers. How each program describes clefs I think is a good comparison between the target audiences.

SCORE — virtually all the information a user would ever need to know about inputting clefs is contained on 2 small pages. (There are 2 parameters on the 3rd page about scaling.)

Dorico — the entire first page contains no actual information about how to input or modify clefs.

I could do without all the additional editorial information about Clefs here, but I think considering Dorico’s target audience there may be many users who benefit from this. Certainly I would prefer a slimmed-down manual without additional information that I don’t need, but a user coming to Dorico from Cubase that isn’t used to notation may need this type of info. The diversity of experience of Dorico’s target audience I think correctly calls for a different approach than the fairly unified user base that SCORE has/had.

2 Likes

Can’t argue with that.

I have frequently had cause to complain about the lack of help given in the Dorico manual. I see now from this discussion that the problem is that there is a Steinberg party line on how manuals should be written. It seems to be prettty inflexible, and explains why Lillie is forced to push back against suggestions for improvement.

The reason why the manual is so counter-intuitive to my way of thinking may be that the Steinberg manual writing specification is designed for the German mind, which is very different from the English or American way of doing things.

Personally, I have just given up on the manual, as I find it too time-wasting, without telling me what I want to know. I mean no disrepect to those who compile it and I am sure they are doing the best job they can within the constraints put upon them by Steinberg.
David

1 Like

I think that assumption may be a stretch that does a disservice to the folks at Steinberg, an international company.

I don’t consider the issue to be language or racially based. It’s a structural issue that for some very strange reason is being avoided. It would be exactly the same for a Swahili user if there was a Swahili version of the manual. It’s all about finding solutions quickly. If something is possible then it should possible to creat a seemless pathway to the answer. To say that how to construct a widget tells you everything you want to know about widgets but doesn’t tell you how to construct it is tautological. And then to say it is a user problem because its obvious that the information is somewhere else doesn’t solve the user’s problem. Was that Germanic enough of a description of the problem?:crazy_face:

I have a close family member who works for Bosch, near its headquarters in Germany. Bosch may be international, but make no mistake, it is a thoroughly German company in its corporate culture and methodology! :wink:

3 Likes

I think it’s because the process is governed by an index and links first (i.e. the hierarchy and relationship of topics) rather than an actual customer experience.

The point about creating something like a Reference Manual that’s slimmed down tool for power-user and the Operating Manual that explains concepts and provides examples is a great one.

As for editorial information, I think parts of the manual could certainly benefit from that: consider, for example Instrument Changes and Changing Instruments. The former is the goal and the latter is the process - right, like the rest of the manual? Wrong!

It’s as if someone has on purpose tried to obscure the fact that one is a player instruction to switch instrument and another is a composer replacing it in setup. There are multiple instances of wording that’s at best confusing but often simply misleading…

1 Like