Development/Season of Docs/2019/BookBrainz

From MusicBrainz Wiki
Jump to navigationJump to search


BookBrainz does not have much documentation, and what exists is outdated. It does not even have a wikipage in this very wiki!

Existing documentations:

These existing solutions need a lot of work!

The developer documentation needs

  • to be updated or moved to another tool
  • set up to update automatically, for example with commit hooks
  • Code documentation can be drastically improved (currently only 40% code coverage)
  • Different parts of the codebase (& different repositories) should be presented separately, but on the same website: webserver, API, ORM, SQL schema,…

The user guide is basically empty, and requires at least:

  • The glossary and FAQ on the website's help page to be consolidated with the user guide
  • Graphical and written explanations of the entities used in BookBrainz, along with their relationships
  • Tutorials for most common use cases (how to create/edit an entity, how to add a book, how to add a relationship, how to merge entities instead of deleting,…) with accompanying videos
  • Style guidelines, how to format edits (capitalization and punctuation, author credits, publisher imprints, reprints and numbered editions, subtitles, series,…)
  • Improve FAQ
  • additionally documenting the history of the idea, development and model of BookBrainz will be helpful.