Development/Season of Docs/2019/BookBrainz: Difference between revisions
From MusicBrainz Wiki
< Development | Season of Docs | 2019
Jump to navigationJump to search
Reosarevok (talk | contribs) No edit summary |
(→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! |
|||
* 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 |
|||
⚫ | |||
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 |
|||
⚫ |
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.