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

From MusicBrainz Wiki
Jump to navigationJump to search
No edit summary
 
Line 19: Line 19:
In order to have an actual set of documentation that users will find helpful and is deeper than the existing Help page:
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 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 information about how this entity is related to other BookBrainz entities (including information about the most important relationships between the two).
* 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:
* 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 create an account
Line 28: Line 28:
=== BookBrainz style guidelines ===
=== 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/
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 BookBranz 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].
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 developer documentation improvements ===

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.