View source for Development/Season of Docs/2019/BookBrainz

== Current situation ==

BookBrainz (https://bookbrainz.org/) 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!

==Ideas==

=== Basic user guide for BookBrainz ===
While a basic user guide was created very early during the development of the project (and is available at https://bb-user-guide.readthedocs.io/en/latest/), there's very little content there and basically all of it is outdated. The only user documentation that exists and is in an usable state is the Help page on the site itself (https://bookbrainz.org/help).

In order to have an actual set of documentation that users will find helpful and is deeper than the existing Help page:
* The contents of the Help page should be moved to appropriate sections in the user guide
* The different entities in BookBrainz should be explained further (probably with one page for each). The explanations should include examples, and also some a way to describe and visualise how each entity relates to other entities (including information about the most important relationships between the two).
* Tutorials for most common use cases should be created, with enough images (possibly screen-capture gifs) and clear enough info for any new user to understand. If useful, video tutorials can be made instead or in addition to written ones. Some ideas of tutorials that might be needed:
** How to create an account
** How to add a book
** How to add a relationship
** How to merge entities instead of deleting

=== BookBrainz style guidelines === 
BookBrainz doesn't currently have almost any style guidelines. Style guidelines are documentation that indicates how to format edits (capitalization and punctuation, author credits, publisher imprints, reprints and numbered editions, subtitles, series, etc). At the moment, the only existing guideline is for the capitalization of English titles, at https://bb-user-guide.readthedocs.io/en/latest/style/language_specific/capitalization-en/
This project requires putting together a list of guidelines that seem important, with the feedback of the BookBrainz developers and community (see the BookBrainz forums at https://community.metabrainz.org/c/bookbrainz). Then for each one, a first draft should be put together with the help of your mentors, which then the community should have a say on. For an idea of what kind of stuff this might involve, you can see [https://musicbrainz.org/doc/Style the list of guidelines for the sister project MusicBrainz].

=== BookBrainz developer documentation improvements ===
While an existing set of developer docs exist at https://doclets.io/bookbrainz/bookbrainz-site/master, they were last updated over a year ago. What we need is:
* To either generate new documentation, or (if desired) move the docs to another tool and then generate it.
* To set the documentation up so it updates automatically, for example with commit hooks.
* To increment the coverage of code documentation (currently only 40% code coverage)
* To present different parts of the codebase (webserver, API, ORM, SQL schema) separately, but on the same website.