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

From MusicBrainz Wiki
Jump to navigationJump to search
No edit summary
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
== Current situation ==
==Ideas==



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


Line 13: Line 12:
These existing solutions need a lot of work!
These existing solutions need a lot of work!


==Ideas==


=== Basic user guide for BookBrainz ===
The developer documentation needs
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).
* 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,…


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 ===
The user guide is basically empty, and requires at least:
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/
* The glossary and FAQ on the website's help page to be consolidated with the user guide
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].
* 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


=== BookBrainz developer documentation improvements ===
* additionally documenting the history of the idea, development and model of BookBrainz will be helpful.
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.

Latest revision as of 17:44, 22 April 2019

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:

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 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.