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

From MusicBrainz Wiki
(→‎Ideas)
Line 2: Line 2:
  
  
−
* BookBrainz has basically NO docs! It does not even have a wikipage in this very wiki!
+
BookBrainz does not have much documentation, and what exists is outdated.
−
* 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
+
It does not even have a wikipage in this very wiki!
−
* additionally a history document documenting the history of the idea, development and model of BookBrainz will be helpful.
+
 
 +
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!
 +
 
 +
 
 +
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.

Revision as of 15:31, 22 April 2019

Ideas

BookBrainz 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!


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.
Retrieved from "http://wiki.musicbrainz.org/index.php?title=Development/Season_of_Docs/2019/BookBrainz&oldid=73344"