Manual annoyances

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:


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

I spend my life using arcane concordances in many languages both on and offline. I have used Dorico’s search engine often and more than 50% of the time I don’t find the solution. I am more often able to do so through another user, on the wider net or by chance. Maybe it is the questions for which I need answers but your answer isnt a satisfying solution to the problem exemplified in how to use the figured bass option in Dorico. As simple an issue of how to draw continuous lines where one is shown beautiful examples but doesn’t actually show you how to do it is a weak form of communication and hasn’t passed the fundamental concept of a manual’s purpose - to help the user to the greatest degree of productivity as quickly as possible. I think it might be a certain inflexibility in the style editorial board.


I agree. I often try the manual only to end up doing an internet search to get the simple instruction I am seeking at the time. One of my biggest gripes about the manual is after reading a long narrative on the related possibilities I find no simple instruction on how to get to the screen the document was talking about. A simple link on every page to simple instructions on navigating to the screen, page, tab, or whatever is being discussed would sure help those of us who don’t live in the Dorico app all day every day.

1 Like

Dear Lillie,
I’ve been mulling over this since you wrote it.
It rather surprised me. Of course that is what I and I’m sure most users would want.
You have described something which by the example on the page is assumed to be created in Dorico and is used as an exemplar and then there is no actual description - in a manual - at that point to show one how to recreate and therefore apply to the user’s specific requirement. The information becomes educationally opaque. Pedagogically, it is at this very point, where the user is motivated to learn, that the one thing they need most in relationship to music publishing isn’t there for the user to learn. Effectively, the thing called a manual is actually a comprehensive glossary of music notation terms with examples. I have Behind Bars or quite a few other such works for that purpose. That there is a need for a glossary is not at issue but for a glossary to become a program manual the terms/concepts need explanation in the program’s language so the user can use the program. If the user’s literacy is also a part of the educational effort of the programmers then surely it should work the the inverse manner describe how to do something and link to an in depth description of the notational intricacies of the concept if the user wishes more information. Now we have a manual and a glossary.
And on reflection, your throw away ‘That’s an interesting thought’ did reach into the patronizing zone. I have set everything from grand opera to avant garde chamber music for major publishing houses and have used all the major music software except Henle’s and A&Rs in-house programs over the last 35 years. I read manuals, and in the old days I would read them cover to cover. I attempt to do the same with online equivalents although it is easy to go down rabbit holes with hypertext linking. I think my experience might account for something more than a throw away.
Finally, to say “I’m not sure that’s how we would approach something like that.” is equivalent to a politician saying that it doesn’t fit with the terms of reference in an enquiry - it is dismissive. It implies that actually, you don’t intend to do any such thing. Even if this is not what you intended that’s how it comes across. I didn’t need to start this thread except for the fact that I thought I could be helpful.

1 Like

Arguments online are rarely helpful and I generally steer clear, but I’m going to make an exception here.

I’m sorry, Lillie’s comment was not the slightest bit patronizing. I read it as common courtesy and a willingness to consider a different viewpoint in an effort to improve the manual. Remember, it’s been stated numerous times that the manual has to be presented according to certain guidelines that are beyond her control. I don’t know why we would expect a response of, “You’re absolutely right, and I’m going to rewrite the whole thing immediately.”

I’m not in disagreement with all of the points you’re raising about how the manual could be improved, but I have to object strongly on that point.

The direct access we get to the team here is really uncommon, and I think should be treated with a little more appreciation.


Dear Dan,
I’m sorry you have read my post in that manner. I think I left the possibility of my misinterpretation of her actions clear in my second last sentence.
Notwithstanding, circumlocution rarely provides a means of getting to the heart of any problem.
Direct approaches may be less palatable but at least one knows where one stands.
We have become an easily offended overly censorious civilization.

With respect, it has nothing to do here with being overly sensitive. And nobody needs me to defend them. It’s about professional courtesy, and giving the benefit of the doubt when there is a potential misunderstanding.

Lots of forums online are pretty horrible. We’ve worked hard together as users to keep this one gracious and respectful.


It strikes me that this complaint is more to do with structure than anything else.

If you find yourself on the description page for Lines or for Figured Bass (or whatever), you either have to look to the Related Links at the bottom or to the left sidebar (the manual is organised in chapters). Carlo, you said further up the thread that something or other could be mitigated by hyperlinks - if you can list specific situations where relevant hyperlinks are actually missing, please do mention them.

And it bears saying that in written text, tone of voice is often imperceptible and/or misinterpreted. We’re all human beings with our own perspectives and our own feelings, and those feelings are easily hurt (note to self: remember this!).


Just as understanding the logic behind Dorico (different from most other notation programs) is important understanding how to work with it efficiently and productively, understanding the logic behind the Steinberg manuals is important to using them effectively.


Suitably chastised.

And that’s the point. Why should one have to look somewhere else for the very reason you’re on the page in question? It would be (technically) very easy to have that information in a popup on the page rather than suggested hyperlinks to somewhere else if stylistically you didn’t want to show the methodology in the immediate description - though I’d personally prefer that.
To Derek’s point below. There’s helpful style and unhelpful style. To say it is the user’s fault in not understanding the house style may say more about a stylistic inadequacy than helpful practice.

Lillie, I’m sure you will not welcome this, but here goes…

Can I request that you separate the Windows from the Mac documentation?

Keystroke combinations are complicated enough without having to constantly filter the ctrl/cmd alt/opt instructions! I’m sure the resulting documents would be much easier for users of each persuasion to learn.

Also the documents would be quite a bit shorter and easier to search!

What this thread shows more than anything is that different people want different things from the manual. It is impossible to cater to them all. Every additional line of clarification for one person clouds the salient point for another.

I’m someone who by nature tries to read as little documentation as possible, but I have recently taken to searching when I’m up against it, and every time, the manual has provided me with the information I needed. I am prepared to search around on a few pages.

The videos, which are also excellent, are where I would look for work-throughs of an example, complete with key presses.


I will add this : as the main contributor to the French FB user group, I’ve been helping a fellow Dorician to understand expression maps and how to build them. Since the documentation in French just arrived some days ago, I have been curious to see how it was explained — as a day-1 user, I’ve been used not to use the manual since by then there was none. We used the forum and the version history a lot.
I was pleasantly surprised, everything was there. And my fellow Dorician probably didn’t look at it. I guess the days of RTFM (in French) are arrived!!!




I’m looking at page 1166 of the PDF manual ( where the section in Lines starts. Basically everything to do with Lines is in the following 35 pages, and it follows the same structure as the left sidebar of the WebHelp. One notable exception is the “input methods for lines” topic, which is linked to; that one’s ~700 pages back within a chapter that’s dedicated to input methods.

If I remember previous discussions correctly, the segmentation is a house style thing, but also a search engine optimisation thing. If you’re coming to a topic via a search engine, it’s anyone’s guess as to whether you’re going to land on the “This is what Lines do” topic or the “Edit Line Annotations” topic or any number of other topics. It’s quite likely that it won’t be the page that tells you how to input lines, but if every page that has anything to do with Lines has instructions for how to input lines then that would dilute the intended content of that page. Not to mention that, given the PDF manual is generated from the same components as the WebHelp, chunks would then need to be taken out of the PDF manual.

As to popups being technically easy, don’t most browsers block them these days?

I’m tempted to lock this thread because I’m not sure we’re in helpful territory. That is not out of any desire to stifle discussion about the documentation, but rather because I’m not sure this particular thread is achieving anything productive, and might be leading towards engendering some ill-feeling that I think would be best avoided. I won’t close the thread at this point, but please consider this a warning that it is sailing close to the wind.

And, for what it’s worth, let me give you my perspective on the issues covered in this thread. With any project there are competing priorities. Obviously the foremost priority is to help Dorico users find the answers they need. But there are other very important priorities that come close behind: to make the documentation maintainable (in the same way that the software must be maintainable); to make it consistent; to make it cost-effective to translate into other languages; to make it work effectively as an online-first publication where the reader can start at any page (and to therefore make it easily indexable by search engines). It also must fit into the company’s established working practices when it comes to the tools used to write, publish, translate and maintain it.

Dorico users in general should hopefully not have to worry about anything other than the foremost of these priorities, namely that they should be able to find the answers they are looking for. We in the Dorico team try our best to be open and transparent in our communications with our users, which is why several members of the team devote a lot of their time – both their working time and their free time, such as (say) at 11.30 on a Saturday morning – to try to help them work successfully with the software. But just because you know a little bit about what goes on “behind the scenes” you don’t know what the real decision-making process is, or what the constraints truly are.

In the end, the information you need is all there. You do need to understand the way the manual is structured in order to use it effectively. We are not going to fundamentally change the structure of the manual, but we certainly can consider how best to communicate that structure so that you can find your way around it more easily.