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

Documentation about seeding entity forms