Project documentation — please contribute!

[Leonard Vertighel]

Dear community, in order to improve the currently sorely lacking documentation for the Petrucci Music Library website, we are now looking for help with the Project documentation.

Please consider donating a little of your precious time to this effort. Even if you know nothing about the technicalities of the site, you can still help us with the organization, or by "test reading" the documentation to verify its comprehensibility, etc.

Feel free to post comments, remarks, suggestions, questions, criticism, etc. in this thread. Thanks in advance to everyone who is going to help, no matter how much or how little.

[Peter]

Ah, great, finally someone who takes initiative for this long lasting weak point of IMSLP. Do you plan to involve only the help pages and technical pages, or also the complete contributor portal with all its semi-encyclopaedic pages? Probably not. But the submission guide, and the guidelines, can be...

[Leonard Vertighel]

The contributor portal I think yes.

What do you mean by "semi-encyclopaedic pages" - work lists, publisher info, etc.? It may be a good idea do develop some guidelines for those, to have a modicum of uniformity among pages of the same type.

[Peter]

Yes that's what I mean. OK, than we'll start this ball rolling! I can help during christmas holidays and in end january.

[imslp]

I've already talked with Leonard about this, but documentation is one of the most lacking sections of IMSLP currently. Most of the templates and stuff is actually on the wiki, but nobody knows where they are or how to edit them, which defeats their purpose...

I've already pointed Leonard to examples that should be intuitive enough to write the documentation on. If there are any questions please do ask me.

When I get some free time I'll also contribute to the documentation project, but I also have several new features that I have to implement, so I may not be able to do much myself...

[jujimufu]

I would like to get involved with the Help: re-organisation

One suggestion would be to have a kind of Help: sitemap for Help:Content, so users would be able to just find any help link from that menu, and each one of the six main Help categories (contributing scores, adding and correcting info, files, community, internationalisation and advanced) (if we stick to those) will have its own group of help files, with its own menu/TOC.

Alternatively, if we don't want to scare away shy users, we could only have six links in the Help:Content page, each one of them linking to the respective category, with a description about what is the content of that Help directory. This way, it would look a lot more approachable and less scary, and would be able to redirect users to the appropriate help category/file without much trial-and-error as to where is the information they're looking for.

Also, it would be great if it was very very clear where the respective Help file is in the submission forms (e.g. in the Add Composer form, if there was a clear link somewhere that read "Help" or "Need help adding a composer?" or something like that - which would provide quick answers to potential problems people might encounter.

Leonard: would you need help with the actual writing? I'd be more than glad to help out (if the project is still running - I noticed Ed's reply is almost a year old... :X )

[Leonard Vertighel]

I would like to get involved with the Help: re-organisation

Thanks for the offer, and apologies for the delay.

One suggestion would be to have a kind of Help: sitemap for Help:Content, so users would be able to just find any help link from that menu, and each one of the six main Help categories (contributing scores, adding and correcting info, files, community, internationalisation and advanced) (if we stick to those) will have its own group of help files, with its own menu/TOC.

I think the "sitemap" should be the page Help:Content itself. Every help page should be linked from there, and the page should be structured according to the help categories. If it gets too big, we can still consider splitting it up. Grouping related pages by means of a common navigation bar probably would be helpful, too. In some cases it might also be useful to have a 'previous'/'next' type navigation for sequential reading of an entire section of the documentation. I also started an alphabetic index at Help:Index.

Also, it would be great if it was very very clear where the respective Help file is in the submission forms (e.g. in the Add Composer form, if there was a clear link somewhere that read "Help" or "Need help adding a composer?" or something like that - which would provide quick answers to potential problems people might encounter.

I'm currently working on overhauling the submission forms. One of the goals is to better integrate the documentation, which currently is in a column to the right of the actual form. Clearly we could add links to more in-depth info if needed.

Leonard: would you need help with the actual writing? I'd be more than glad to help out (if the project is still running - I noticed Ed's reply is almost a year old... :X )

Thanks for the offer, in fact I think the Help pages need a lot of attention. I think the most important steps at the beginning would be:

• Making a complete inventory of all existing documentation (Help: and IMSLP: namespaces)
• Mercilessly deleting all outdated documentation. Better no info than wrong info.
• Organizing the remaining material in a clear structure, so that it is easy to use both for new users (basic info to be read more or less sequentially, depending on the task the user is interested in: score submission, translation, etc.) and veterans (more reference-like sections).
• Only at this point does it really make sense to fill in the gaps by writing the missing parts of the documentation.