Development/Season of Docs/2019/MusicBrainz: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
(link to Release Editor Seeding page)
No edit summary
Line 1: Line 1:
==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==
==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:
* Musicbrainz already has https://musicbrainz.org/doc/ as well as dev docs like https://musicbrainz.org/doc/Development and Guidelines https://musicbrainz.org/doc/Style and beginner-guides and how-to's; https://musicbrainz.org/doc/Beginners_Guide .

* However much of things are outdated and will need updating and improving.
'''''Introductory guides'''''
* Documentation for our web service needs improvement:

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/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.
** [[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===
* We have no documentation about seeding entity forms ([[Development/Release Editor Seeding]] excepted). e.g. https://musicbrainz.org/artist/create?edit-artist.name=foo&rels.0.target=b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d
* We have no documentation about seeding entity forms ([[Development/Release Editor Seeding]] excepted). e.g. https://musicbrainz.org/artist/create?edit-artist.name=foo&rels.0.target=b10bbbfc-cf9e-42e0-be17-e2c3e1d2600d

Revision as of 17:54, 22 April 2019

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