Photo by Kaitlyn Baker on Unsplash
Documentation is essential to the adoption of open source projects as well as to the success of their communities. Season of Docs brings together technical writers and open source projects to foster collaboration and improve documentation in the open source space.
Open source organization for proposal
Title of technical writing project proposal
Improving the Documentation Experience for Bokeh Developers
Description of technical writing project proposal
Current documentation state
Bokeh has done a tremendous job in documenting visualization use cases in the User Guide . In the Reference , you can find all the API methods afforded by their models. The documentation has grown large and there is no easy way to find misspellings, repetition errors, or formatting issues in the text .
You can find dozens of code examples on how you might use Bokeh with your own data on GitHub. You can find some of these examples inline in the documentation but not all of them are referenced. Users may spend a considerable amount of time trying to figure out how a tool works without realizing there exists code they can reference. For example, you can use Themes to style a plot on Bokeh but these examples exist in the Reference when one would expect to find an example listed inline or referenced in the User Guide .
Lastly, a subset of the Bokeh documentation could benefit from the inclusion of metadata. Bokeh uses Sphinx to build documentation. Sphinx is a tool that makes it easy to document software projects. This tool does not automatically include any structured data on the HTML pages it generates. Metadata in this case is metadata about the HTML pages. When searching for “Bokeh docs” on a search engine, the results users get back do not describe the content of the page. When sharing links to the Bokeh documentation on social media sites or forums, there is no way to preview the content on the page before clicking on links.
Proposed documentation state
Automated checks for spelling, repetition, and writing style errors
Additional cross-referencing across docs
Different parts of the documentation should link back and forth for a more complete discussion. Users interested in learning more about a topic should be able to navigate to the Reference from the User Guide. Users interested in seeing an example of an API method should also be able navigate to the User Guide from the Reference. All examples found in the GitHub repository should either be referenced or exist inline in the documentation.
Metadata across docs
Search engines extract and collate the metadata found on web pages to describe and classify them. Including metadata, such as descriptions, in the Bokeh documentation would give users more data when browsing search engine result pages. This metadata would also provide rich previews when sharing links to these pages. Some metadata would appear alongside these links, giving readers a preview of the content before clicking. Specifying HTML metadata, like a description, can be done by manually adding the the "meta" directive on some pages. Later, Sphinx extensions can be developed to automate adding relevant metadata throughout the entire documentation.
- Stay active as a contributor by tackling documentation issues
- Start a friction log to keep track of areas of documentation needing improvements
- Establish project requirements
- Schedule a time to meet with mentors
- Agree on method of providing progress and updates
- Set up and test Vale to check for existing spelling and repetition errors
- Identify terms to ignore that cause spelling errors like http, Bokeh, JupyterLab, etc.
- Add a new text file with list of terms to ignore when checking for spelling errors
Week 2 and Week 3
- Identify suggested terms to use throughout documentation for consistency
- Add a new style guide for suggested terms
- Configure Vale to run on every pull request submitted to Bokeh
Week 4 and Week 5
- Start working on improving cross-referencing across Bokeh documentation
- Identify existing Bokeh examples not shown in-line in documentation
- Link examples in the documentation to the source code location on GitHub
Week 6 and Week 7
- Review topics covered in the User Guide
- Identify topics to link to sections in the Reference
- Identify pages on https://bokeh.org/ and manually add metadata
- Investigate existing Sphinx extensions that can be used to add metadata across docs
- Integrate existing Sphinx extension or develop a new Sphinx extension to automatically add metadata across docs
- Finish remaining tasks
- Start working on Season of Docs project report
- Finish project report
- Submit project report to Google
- User Guide - https://docs.bokeh.org/en/latest/docs/user_guide.html
- Reference - https://docs.bokeh.org/en/latest/docs/reference.html
- Documentation spelling and formatting - https://github.com/bokeh/bokeh/issues/8448
- Bokeh Examples - https://github.com/bokeh/bokeh/tree/master/examples
- Include example code of PolyEditTool and PolyDrawTool Docs - https://github.com/bokeh/bokeh/issues/9962
- Add mention of Themes to "Styling Visual Attributes" docs page - https://github.com/bokeh/bokeh/issues/9007
- Reference Guide should link to Users Guide where appropriate. - https://github.com/bokeh/bokeh/issues/9363
- Sphinx - https://www.sphinx-doc.org/en/master/
- Vale - https://github.com/errata-ai/vale
- Vale Linter - https://github.com/marketplace/actions/vale-linter