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

From MusicBrainz Wiki
Jump to navigationJump to search
No edit summary
No edit summary
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== 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==
==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 ===
* BookBrainz has basically NO docs! It does not even have a wikipage in this very wiki!
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:
* BookBrainz will need docs explaining the way to edit and guidelines, it will need docs that document what each type of entity is and how we plan on altering things in the future
* To either generate new documentation, or (if desired) move the docs to another tool and then generate it.
* additionally a history document documenting the history of the idea, development and model of BookBrainz will be helpful.
* To set the documentation up so it updates automatically, for example with commit hooks.
* Updates to the presentation of LB and AB (the front page of both is really dense text that isn't welcoming to new users) - not sure if this is "docs" or "design"?
* To increment the coverage of code documentation (currently only 40% code coverage)
* AcousticBrainz - what is the process of signal processing -> feature extraction -> datasets + model generation -> highlevel features
* To present different parts of the codebase (webserver, API, ORM, SQL schema) separately, but on the same website.
* How does ListenBrainz store and process your data, who else can see it, and what can they use it for

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.