Development/Season of Docs/2019/BookBrainz
BookBrainz does not have much documentation, and what exists is outdated. It does not even have a wikipage in this very wiki!
- 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.