Development/Season of Docs/2019/BookBrainz

Ideas

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

Existing documentations:

• Auto-generated developer documentation https://doclets.io/bookbrainz/bookbrainz-site/master
• User guide & style guidelines: https://bb-user-guide.readthedocs.io/en/latest/
• The website's help page: https://bookbrainz.org/help
• Development setup and troubleshooting on github: https://github.com/bookbrainz/bookbrainz-site/

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.