User-created documentation
There are a variety of user-created resources on using MuseScore other than the Handbook, and I think it's time to expose these on the site in a way where the average user can find them. I've talked with Thomas some about this a while back when I wrote my lead sheet tutorial, but I figured others have have some ideas here too.
My feeling is that there should be a new area on the site for user-created documentation above and beyond the Handbook. My lead sheet tutorial (which is already in the site's wiki format and hosted here) and be accessed from there. I have a couple of other similar documents in mind to put together, including one on customizing chord symbols. The stuff in the "Snippers" sections falls into this category, but that section appears narrowly enough defined that I am not sure simply adding on to that as is makes sense. I think John Sprung's CheatSheet would be another obvious candidate; this is currently a Word document. Katie Wardrobe's series of tutorials - currently on another site - could also be made visible here, probably as links. There's a few existing forum posts that are useful enough that we might want to link to them more or less as is, or encourage people to flesh them out and copy them to new nodes in this new section. And I'm sure there are other blog articles or other resources that could be linked in. By creating a place to house and access this sort of ancillary documentation, I'm hoping that in itself would spur the creation of more.
I'm thinking there could be a "Documentation" link that replaces the current "Handbook" link in the main menu at right of all pages here. That would take you to a landing page from which you could access the handbook *or* these other resources. Or if people thought one-click access to the online handbook from the forums were especially important, we could leave the "Handbook" link intact but simply add a new "Other Documentation" link next to it. Or replace the "Snippets" link with one to this new page, and access the existing snippets from there.
I haven't been that involved with other open source projects, but I've seen enough to know that wikis for this sort of thing do exist and can be quite useful. Of course this has the potential to get out of hand if too many people contribute overlapping and conflicting info, and there would be no guarantee it would all be up to date as new versions of MuseScore come out. But I don't think those are unsolvable problems, and I think I'd rather have those problems to solve than not, if you know what I mean.
Comments
Good call Marc. I have been pondering over the same thing, one unified documentation page where you can find links to all sort of support pages. Not so long ago, another open source community at drupal.org redesigned their website and tried to improve the menu system and therefore the guidance of first time users. I think they succeeded well and it pushed me to think how to improve musescore.org. But so far, I didn't really start the job, so let's get it done now.
To start, I created a tutorial page: http://musescore.org/en/tutorials
Next thing is a sort of documentation page. Do you envision a sort of panel page, containing the complete handbook outline left and right a stacked set of blocks containing the list of (video) tutorials and snippets? Or simply a page with links to the handbook page, tutorial list, video tutorials and snippets?
In reply to Let's get this started by Thomas
that appears in the upper right corner:
Download
Features
Screenshots
Handbook
Leadsheet Tutorial
Beginners' Quick Answers
Forums
Snippets
Plugins
Development
Donate
If, after a while, there are too many of them, it may make sense to put them a click farther away in their own list. If new users don't find what they need promptly, they decide to forget about MuseScore.
-- J.S.
In reply to I think the right place is to add them to the existing list... by John Sprung
While it's possible the "beginner's quick answers" could have its own place on the main menu, I definitely don't think all tutorials belong there, and in particular, my leadsheet one doesn't. Nor does any other that I'm aware of. They are just too specific in nature to deserve links on every page. A main menu link to a top level documentation page with links to other resources, perhaps organized by topic, makes way more sense to me.
Given that a new user really has no way of knowing what to expect out of Handbook versus Documentation versus Tutorials versus Snippets, and given that the handbook is already present in the software itself, my inclination is to have a single Documentation page in the main menu from which one could access all those other things. I'd make the Handbook and Beginner's Quick Answers most prominent, and then start listing others individual tutorials. Right now, a simple list might suffice, as there are probably no more than a dozen or so items to list, but I'd hope that in the near future, there would be enough items there to warrant dividing by topic. Given that it isn't completely clear how such a topic division might look, though, I'd just as soon wait and see what other tutorials develop before trying to enforce some of categorization scheme.
I think the "beginner's quick answers" has the potential to be worth putting in the main menu separate from the generic Documentation link I am proposing. But realistically, if that were to be the case, I think you'd probably want to now spend some time on the presentation - getting it into Wiki format, maybe thinking about wording issues to make it seem a bit more consistent with other "official" MuseScore documentation (ie, the handbook). Don't get me wrong; I think it's a great document for what it is already. But in order for it to feel right to me on the main menu, I think the presentation should probably conform a bit more. And then there could be links to specific handbook topics, other tutorials, etc.
In reply to While it's possible the by Marc Sabatella
then surely the screenshots and snippets should also go elsewhere. Perhaps features and plugins, too.....
I'm working on a formalized version of the quick answers.
-- J.S.
In reply to If the Leadsheet Tutorial doesn't belong on the main menu, by John Sprung
The way I see the distinction is the leadsheet tutorial is a tutorial on a very specific usage of MuseScore, of interest to probably a fairly small percentage of users. You'd need dozens of such tutorial to add up to complete documentation. That's why it seems like the sort of thing that doesn't belong on the main page. I'd have the same reaction if someone put together a tutorial on how to create, say, a passage of music with all eighth notes represented with flags instead of beamed. Useful, sure, but I'd more expect to see that under a top level Documentation page than linked directly on the main menu. Why clutter up the main menu? That's what hierarchies are for.
Your document, on the other hand, cuts across different usage scenarios and would be of interest to *all* new users. That's why I see it as more front-page worthy if anything were, although really, it would also be no trouble to find it under the main Documentation menu. A new user would see "Documentation" in the main menu and I don't think there would be a moment's doubt in their mind that this would be the place to go for info on how to use the program, and if they found both the handbook and your writeup prominently featured there, I don't think anyone would find that awkward.
I'd definitely agree that "snippets" doesn't really need to be top level. Plugins is less clear; if not there, it isn't obvious at all where you'd put them instead. Whereas everything documentation-related could very naturally fit under a "Documentation" heading. And "screenshots" I think is also main menu worthy, as it is not really documentation - it's something a prospective new user might want to take a quick look at to get a big picture feel for the program without having to actually read the documentation for all the details.
In reply to The way I see the distinction by Marc Sabatella
I'd have guessed that the usage might break down about 60% leadsheet / 40% grand staff and bigger scores. It would be interesting to do a survey on that.
I agree that we shouldn't clutter up the main menu, but at this point there aren't enough documentation items to be a problem. We can go to a second level documentation page if and when we have the good fortune to have that problem. As to what goes there, if we want to grab and hold new users, "best foot forward" should be the guiding thought. That's why something that's thorough and well written, like the Leadsheet Tutorial, deserves equal status with the more general, but frankly less well written, handbook.
I really have been working on the formalized version of the "Quick Answers". Strangely, it's harder than writing the original version. Alas, I just got a load of real work I have to do, so let me show you what I have so far. Bear in mind it's a work in progress, only a first pass on part of it.
-- J.S.
In reply to Hi, Mark -- I guess it depends who you hang with .... by John Sprung
My sense of how common lead sheets are among MuseScore comes from the questions I see posted here, the scores I see posted in the sharing sections, and the responses that come up when threads on lead sheets come up. Based on all that, I'd put it at under 10%.
As for how many items there are, I think there easily over a dozen right now, including your writeup, my tutorial, Katie Wardrobe's tutorials, the Snippets, and a handful of forum postings. We're clearly past the point where they all could be top level items, I'd say. So if something is going to make the top level along side the generic Documentation link, it would have to be as important as the rest of all that documentation put together - that's how I look at it. In my mind, the handbook is really the only thing that obviously fits that description, with your writeup the only other possible candidate in my mind. I know as a new user, if I saw two main menu items "Documentation" and "Handbook", I'd be clicking Documentation first, but if I also saw something that said "Quick Start Guide" or some such, I might try that first. But I'd also kind of expect anything on the main site menu to be "official" stuff.
Your first pass looks good to me. It's a fine line to walk between making it detailed/comprehensive enough to be useful but short enough to not be overwhelming. One advantage of doing it online would be that more detail could be made available after a click, allowing it to be kept shorter at first glance.
In reply to My sense of how common lead by Marc Sabatella
There are a lot of musicians out there who play clubs and private parties. Probably a lot more who have day gigs and play on the side for little or no money. There are even big bands like that, I have a friend who plays bass in one. MuseScore would be ideal for them. (With a decent sound font, you could even make MMO's for free....)
Ah, I wasn't aware of those forum postings that may deserve permanent status. In that case, yes, it's time for a second level.
Thanks, I'll keep hacking away at the formal rewrite. But I really don't think it's anywhere near as good as the original. If anything, it would be better to do an informal re-write of the main Handbook to establish a consistent and natural tone.
My idea was to keep the "Quick Answers" short enough, like 4-5 pages, that users would just print it out and keep it on the desk for quick reference. It should be possible to make that work plus add clickable links to other documentation for its online version.
-- J.S.