[MEI-L] Documentation for MEI v4

[Johannes Kepper]

Dear all,

In preparation of our "ODD Friday" Documentation Sprint on coming Friday, we've prepared a new chapter structure for the MEI Guidelines. In the past, every module in the specs had its own chapter in the Guidelines. Some changes to the code for v4 have made this impractical, and indeed there are good arguments to not organise documentation in the same way as the code. We hope that this structure is more accessible than the original one:

https://docs.google.com/document/d/1yKIPkjBwfMwbOMVawQxL6uy4EFjdda8WKpp8klFMsyQ/edit?usp=sharing

We would like to gather feedback to that structure, either here on MEI-L or as comments (or proposed changes) in the document. The chapter names are mostly preliminary, and also chapter organisation may change to some degree while working on them. So we're asking for feedback about the general direction, although input about the specifics will be helpful for the actual implementation.

That said, we hope that on Friday many of you will be available. It's then when we want to assign volunteers to those chapters. As you can see from the document, most of the content is already available, and just needs to be checked for compatibility with the current schema. If there is sufficient contribution from the Community, updating the Guidelines will be an easy task.

Friday itself isn't necessarily a formal conference call. Instead, Benni and I will stand ready to answer questions. We recommend that people register on Slack for easy communication. I will be available on Skype as well (my user name there is j.kepper), and of course we're answering to emails. However, to get things started, we will offer a conference call on Skype at 2.30pm Central European Time (1:30pm GMT, 9:30am EDT, 6:30am PDT). Please reach out earlier to allow accepting new contacts etc. ahead of time. After the meeting, we will take the further work on this to GitHub, and assist people as needed.

All best,
Benni and Johannes


> Dear all,
> 
> Benni and I are currently preparing a work plan for revamping the Guidelines section of the MEI Documentation (https://music-encoding.org/guidelines/v4/content/). The problem is that this Documentation still reflects the state of MEI v3, which in some parts differs significantly from the current model. The differences can be traced here: https://music-encoding.org/archive/comparison-4.0.html, but that doesn't provide a detailed explanation of the differences. For that purpose, we currently only have the release notes, available from https://github.com/music-encoding/music-encoding/releases/tag/v4.0.0.
> 
> It is comprehensible that people are getting confused when reading that documentation, and we would very much like to resolve that situation rather sooner than later. However, it's clear that we can't do this alone, or in a week's time. As a first step, we will introduce a warning at the top of each chapter explaining the situation, and redirecting people to work with the Specs (under Elements etc.) instead. Next, we would like to gather and coordinate a group of people that is willing to help with updating the Guidelines. For this purpose, we plan to have regular open meetings on Slack / Skype / …, on every odd week's Friday (pun intended), where people can jointly work on the documentation, ask questions and so on. This will be hop on / hop off meetings – we're happy about everyone who will be able to join us, and we don't expect formal commitments. Of course, work on the documentation can be done at other times as well, but we'd like to make ourselves available for discussion and so on. Ideally, something like this (maybe with a lower frequency) will be helpful for the continued development of the schema, but this has much lower priority right now.
> 
> The first ODD Friday will be 29 March, then 12 April, and every other week from then. We will be available from 2pm German time (Germany switches to summer time on March 31, so I leave it to you to identify what this means for you…). We encourage everyone to join us, even without technical knowledge about MEI – this is about writing comprehensible documentation, where it's always good to have a broad range of expertises. If you're uncertain, please contact Benni and / or me directly, and we will make sure that everything will work for you.
> 
> Thanks very much, and all best,
> Benni and Johannes
> 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: Message signed with OpenPGP
URL: <http://lists.uni-paderborn.de/pipermail/mei-l/attachments/20190327/e6f11bab/attachment.sig>