Development/Season of Docs/2019/MusicBrainz

Current situation

MusicBrainz already has a long (possibly too long) set of docs, that can be browsed starting at https://musicbrainz.org/doc/MusicBrainz_Documentation. These include standard user-facing docs about what each thing is, as well as developer-focused docs (https://musicbrainz.org/doc/Development), style guidelines indicating how different data should be entered and formatted (https://musicbrainz.org/doc/Style), and per-action guides and how-tos (mostly linked from the box at https://wiki.musicbrainz.org/Template:HowtoBox).

However, much of the user-focused documentation is outdated and will need updating and improving.

Ideas

New set of core documentation for website users

While our more specific guides are usually reasonably up to date and seem to do their work fairly well, the more general introductory pages are either quite out of date or generally leave quite a bit to be desired. Since we're hoping to get a fresh start on a new documentation platform (still to be decided exactly, but not MediaWiki anymore, and probably using either Markdown or React templates), we should start by getting a new set of core documentation for our users.

This has two main parts:

Introductory guides

To update (or write from scratch) the main introductory guides:

• https://musicbrainz.org/doc/Beginners_Guide
• https://musicbrainz.org/doc/Introduction_to_Editing
• https://musicbrainz.org/doc/Introduction_to_Voting

The first two of these cover probably the most basic things a new user might want to do, but they do it in a way that is not always too useful. They should be rewritten (and possibly combined) in a way that lets a new user go from "so what is this MusicBrainz thing" to "what am I able to do to contribute and what are the main things I should know", probably with links going out to more detailed guides for different steps such as https://musicbrainz.org/doc/How_to_Add_an_Artist and https://musicbrainz.org/doc/How_to_Add_a_Release. The voting guide is probably more up to date but would still benefit from being made clearer to users.

Core entity documentation

To write a new set of docs for our main entity types (artist, label, release, etc.). Those can be based on our current documentation (such as https://musicbrainz.org/doc/Release and https://musicbrainz.org/doc/Label), but those are very dry and not really user-oriented, being basically a (sometimes fairly technical) description plus a list of different fields and parts the entity has. The task of the writer here would be to work with us to figure out a better way to explain what the entities actually are and how to use them in a way that tries to answer the doubts the user might actually have, and then actually write those explanations.

Documentation for the MusicBrainz web service / API

• • Development/XML_Web_Service/Version_2 is missing information about authenticating with OAuth.
  • Development/JSON_Web_Service is incomplete, lacking a useful description of the data format, and any important differences with the XML web service.

Documentation about seeding entity forms

MusicBrainz's entity forms, which users submit data through, allow for "seeding" the forms with pre-filled in data via URL query parameters. For example, to open the "Add Artist" form with "Queen" filled in for the name, you can open a link to https://musicbrainz.org/artist/create?edit-artist.name=Queen. This is a trivial example, but in fact all of the fields on the page can be seeded with pre-filled data (even Relationships: https://musicbrainz.org/artist/create?rels.0.target=b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d). This can be useful for scripts which want to semi-automate submitting data to MusicBrainz from another source (e.g a website containing metadata).

While we do currently have documentation for seeding releases (Development/Release Editor Seeding), for other entities we don't even document that it's possible, let alone how to do it. The technical writer's task would be document entity form seeding in a way similar to the way do for releases, identifying all possible URL query parameters and which form fields they map to, with the help of their mentor.