Documentation: Glossary vs. Snippets

• Dec 1, 2010 - 13:06
Type
Wording/Translation
Severity
S4 - Minor
Status
active
Project

There are currently two documentation efforts going on which are complementary to the current handbook. There is Glossary and Snippets.

Glossary

Requested by lolivier at http://musescore.org/en/node/7496
As he defined, it is meant as a quick reference, together with definitions and should be covered by the translation system.

Snippets

Requested by Fred Volgel at http://musescore.org/en/node/8034
As he defined, he was looking for a cheat sheet which would show all things you can do with MuseScore + explanation on how to do it. Again it had to be covered by the translation system.

Defining the difference

You could see there is some kind of overlap in the sense that both could contain the same items (terms/titles), but their properties are different.

Glossary: Term; Meaning
Snippet: Title; Picture; Explanation

Looking at the Lilypond project, they too have a Snippet repository and a Glossary.

The current setup is that Snippets and Glossary will have their own page and one single page only. Once that page has reached a certain state of quality, it will/can be added in the handbook as a child page and it will covered by the translation system.

If you have better ideas how we can improve these two efforts, please comment.


Comments

I'm not happy with the way snippets are currently handled. A handbook page is not appropriate for it. For the sake of testing new solutions, I made a new content type called snippet which has the following properties:

  • Title
  • Description
  • Image file
  • MuseScore file
  • Instructions how to typeset or hack the snippet
  • Links to the handbook pages (optional)

See a sample snippet at: http://musescore.org/en/node/8422
They are currently listed up at http://musescore.org/en/snippets-list

All snippets are editable (wiki) but currently not set to be translatable. Since they can be linked to handbook pages, we can feature snippets under each handbook page.

Hi Thomas
I think its a good idea to make a nieuw start with the Snippets project.
For my self I don't now what to do. To stop with filling and correcting the Snippets pagina and to wait for new instructional?

If you have new Ideas let me know what i can do.

FredPaul

Hi FredPaul,

Let me start with saying that I appreciate enormously the effort and time you have spend on the snippet page. It's thanks to your persistence and continuously pushing the limits, that I know that we will end up some way or another with something good, working and useful. It does mean however, that it might be different from the initial idea. After all, we are in the game of making new things that work on the foundation of online collaboration. Not many have done this before for sheet music market. So although we are not there yet, we should be proud of ourselves with what we achieved so far.

So back to iteration 2. In order to test it, you can make a snippet via:
http://musescore.org/en/node/add/snippet

Once you submitted it, it will be listed at http://musescore.org/en/snippets-list

Give it a try for one or 2 snippets and then we make a new assessment.

Hallo Thomas,

Allereerst Beste wensen voor het nieuwe jaar

Ik heb ondertussen een paar Snippets gemaakt volgens de nieuwe methode. Dat lukt wel aardig maar er zijn wel een paar haken en ogen.

1. Het is voor mij eigenlijk onmogelijk de beschrijving in het Engels te zetten. Dat gaat veel te langzaam en kost mij dus te veel tijd. Zoals je kunt zien bij de Snippets 2 heb ik de originele Nederlandse tekst bijgevoegd en deze tekst door de Google translator gehaald en die tekst staat er ook bij. Ik begrijp heel goed dat er een zeer vreemde Engelse tekst staat, wat ik kan veranderen doe ik, maar verder is het zo als het is. En zullen andere naar die tekst moeten kijken.

2. Mij tekst moet nog wat bijgeschaafd worden en korter maar het lijkt mij goed elke keer een aantal basis handelingen te herhalen . Zoals, Hoe te slepen, menu's te openen e.d. want er zullen steeds beginners zijn die dat niet weten.

3. Het blijf moeilijk... maar niet onmogelijk plaatjes mooi in de linkerbovenhoek van de snippets pagina te krijgen. Een plaatje gemaakt met een teken programma heeft altijd wit marges . Ik denk dat ik het nu gevonden heb door het papierformaat zo klein mogelijk te maken en de wit marges op 0 te zetten.

4. De speciale tekens,kleuren en of onderstrepingen die ik toevoeg in mijn tekst ( een Wordt .doc dokument) komen niet over in de snippet pagina. Dat is wel jammer want verschillende Letters of kleuren kunnen de handelingen vaak verduidelijken.

5.Ik weet niet of het overal toevoegen van een Musescore mnz document overal nuttig is.... maar daar kunnen we het nog over hebben

Tot zover mijn opmerkingen

Ik ga gewoon door met wat ik begonnen ben en hoor wel van jou of er iets veranderd moet worden of moet stoppen.

Hartelijke groet

FredPaul Vogel

Hi FredPaul,

Thanks for continuing this effort. Let's take one snippet at the time before you start doing to much work which is rendered useless.

First of all, I have added a field to indicate the language of the snippet so let's not mix languages through each other. That's simply not maintainable.

I have some remarks on your snippets. It appears to me that some of the snippets enormously overlap the content from the handbook. E.g. the snippet which explains how to create first and second ending volta. Perhaps you are not aware, but this is completely written out in the handbook. See volta .

So, we need consider the following rule: if something is missing in the handbook
- and it is applicable to anyone, then let's write it in the handbook
- and it is applicable to certain use cases, instruments or ..., then let's make a snippet