Development/Season of Docs/2019/MusicBrainz

From MusicBrainz Wiki

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:

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

The MusicBrainz web service allows developers to access our data directly (in XML or JSON format) without having to setup their own copy of the database. It makes up the vast majority of HTTP traffic we handle. But the documentation for it is very lacking.

As an example, data about Bach can be requested at https://musicbrainz.org/ws/2/artist/24f1766e-9635-4d58-a4d4-9413f9f98a4c (for XML) or https://musicbrainz.org/ws/2/artist/24f1766e-9635-4d58-a4d4-9413f9f98a4c?fmt=json (for JSON).

The two main documents needing updating are:

The first document contains general API info, but no real description of the data format returned by the API, other than a couple copied-and-pasted XML samples. The second document contains no real API info, and mostly consists of copied-and-pasted JSON samples. Neither documents the actual data format: What elements/fields/attributes can be returned in each query? What's the data type or possible set of values for each field, which are optional, and which are always present in the output? A goal of the technical writer would be to document this. This may involve restructuring the existing documentation and/or deleting Development/JSON_Web_Service altogether (merging any relevant info into the main API document).

Another objective of the writer would be to document how to authenticate to the web service using Development/OAuth2. Authenticating allows users to (1) request private data like tags and ratings, and (2) submit certain kinds of new data (tags, ratings, collection items, barcodes, ISRCs). This can also be achieved using HTTP digest authentication, but we'd like to deprecate that method. Unfortunately, Development/XML_Web_Service/Version_2 still wrongly suggests to use digest auth and doesn't mention OAuth2 at all. A developer would currently have to stumble on Development/OAuth2 and infer that the "Access token usage" section applies to the web service despite no text or examples indicating that.

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.