Difference between revisions of "Development/Season of Docs/2019/BookBrainz"
From MusicBrainz Wiki
< Development | Season of Docs | 2019
Reosarevok (talk | contribs) |
(→Ideas) |
||
Line 2: | Line 2: | ||
− | + | BookBrainz does not have much documentation, and what exists is outdated. | |
− | * | + | It does not even have a wikipage in this very wiki! |
− | * additionally | + | |
+ | 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:
- 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.