Handbook suggestion: Remove references to previous MS versions
The current Handbook is cluttered with references to previous MuseScore versions. Why? As a technical writer, this strikes me as completely unnecessary. It makes the Handbook much harder to use. (Several times I've found a command in the Handbook, then wondered why it didn't work—because I'd failed to notice the Handbook was referring to a previous version.)
If users had to pay for MS upgrades, it would be different. But MuseScore is free. So rather than feeling obligated to keep documenting previous versions, I suggest you begin each Handbook with something like this:
NOTE: This Handbook applies to MuseScore ver. 1.0. If you're using an older version of MuseScore, please visit www.musescore.org and download the current version to take advantage of the improved commands and features described here.
Comments
See this .
In reply to See this. by chen lung
From the page you referred to:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
The documentation for old versions is mostly for Linux users who tend to be a few releases behind the rest of us because of how software is distributed for that platform... Also people in the middle of a large music project may choose to stick with the version they started the project in...
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Fair enough. But I assume the majority of MS users are using v1.0. So it's considerably more practical, professional, and more normal to maintain a version of the Handbook free from obsolete content.
First, the Handbook bundled with the app: I've never heard of anyone bundling outdated documentation. What possible reason could there be for doing that? The user is downloading the current app. They don't need to stumble through outdated docs; that's just goofy. It could even create the impression the documentation team is being lazy—and we know that's not true, don't we? ;?)
This leaves the HTML and PDF Handbooks.
I assume someone still has the last Handbook prior to MS 1.0, and that it too includes the references back to v0.92. So separate archival Handbooks for pre-1.0 users needn't be created. Just re-upload them and add links to them to the Handbook page. For example, at the top of the HTML Handbook:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NOTE: This Handbook is for MuseScore 1.0 and later. To see the online Handbook for
MuseScore 0.92 to 0.99, click here.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
For the PDF Handbook, change "Download" to "Download MuseScore 1.0 Handbook"; then, below that section:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Older version: Click here to download the PDF Handbook for MuseScore 0.92 to 0.99.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Maintaining up-to-date documentation—and, when it's useful, archival documentation—are important parts of technical writing. Yes, it's a bit more work, but our duty is to the users, not to our own convenience.
There's another important reason to bother doing this: It makes it less likely that new users will get frustrated and give up. Notation apps are especially challenging because there are virtually no UI standards from one to another. So it's really important to keep your docs as simple and humane as possible.
Heck, I'll even do most of the work: If you'll give me a copy of the current Handbook in your development format, I'll edit out the obsolete references, retitle it, and send it back to you. Such a deal!
Cheers, Andy
In reply to Documentation Practices 101 by Andy Fielding
Hi Any,
Thanks for jumping on this issue. It's a topic that will become a real issue when we decide to start documenting MuseScore 2.0, but up until today, we don't have a strategy yet how to manage it.
Strategy 1: The handbook is written for one release only, being the upcoming release.
Strategy 2: The handbook is written for two releases, being the upcoming release and the previous stable release
Strategy 3: The handbook is written for all releases
When we decide to write the online handbook for two or more releases at the same time, we could make a solution which makes it possible to only display one version at the time: when writing instructions for a certain version, we add a class html tag like
class="1.0"orclass="0.9.6"which it displayed or hidden depending on what version you want to see the handbook for. With a set of links on the online handbook, one can toggle between different versions of the handbook. The only thing I don't know yet is how to deal with the condition for version X.X and above, ... which will require an extra class to be added likeclass="0.9.6 above"So to conclude, we need to decide first for how many release we want to write the online handbook for. Technically, everything is possible. Question is merely whether we can come up with a simple solution.
In reply to Documentation Practices 101 by Andy Fielding
To make the process clearer, MuseScore handbook is written collaboratively online. This is the development format. The english handbook is editable by anybody. Before every release or prerelease, the PDF handbooks are commited to the source repository and end up in the release (Help -> local handbook). The link on musescore.org (download PDF handbook) always link to the last version in the repository.
For all other 30 languages, the handbook is a translation of the english one and it's edited by a team for each language online on musescore.org.
Windows (75%) and english (50%) are just a part of the musescore user community.
I tend to agree that the online documentation should only be for the two last release.
Since you're a technical writer, could you please take a look at my Quick and Dirty MuseScore CheatSheet? It's in another thread here under documentation. I just posted a revised version as a .DOC file at the end of the thread, so please ignore the inline one from a couple days ago.
I'm hoping to turn it into something that answers 90% of a beginner's questions with 10% of the words of a full manual.
Thanks --
-- J.S.