Current documentation state

Bokeh has done a tremendous job in documenting visualization use cases in the User Guide [1]. In the Reference [2], 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 [3].

You can find dozens of code examples on how you might use Bokeh with your own data on GitHub[4]. You can find some of these examples inline in the documentation but not all of them are referenced[5]. 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 [6][7].

Lastly, a subset of the Bokeh documentation could benefit from the inclusion of metadata. Bokeh uses Sphinx to build documentation. Sphinx[8] 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

Vale Linter [9] is available as a GitHub Action [10]. It checks for spelling, repetition, and styling issues on every pull request. This Action can be added to the existing build process Bokeh uses for pull requests on GitHub. Automated checks would find existing errors in the documentation to fix. This technology would prevent future errors from creeping into the documentation. Vale Linter can also enforce a consistent writing style across all documentation. For example, suggesting the term "JavaScript" over "Javascript," preferring active voice over passive voice, etc.

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.

Timeline

Pre-community bonding

• Stay active as a contributor by tackling documentation issues
• Start a friction log to keep track of areas of documentation needing improvements
  

Community bonding

• Establish project requirements
• Schedule a time to meet with mentors
• Agree on method of providing progress and updates
  

Week 1

• 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
  

Week 8

• Identify pages on https://bokeh.org/ and manually add metadata
• Investigate existing Sphinx extensions that can be used to add metadata across docs
  

Week 9

• Integrate existing Sphinx extension or develop a new Sphinx extension to automatically add metadata across docs
  

Week 10

• Test Sphinx extension(s)
  

Week 11

• Finish remaining tasks
• Start working on Season of Docs project report
  

Week 12

• Finish project report
• Submit project report to Google
  

References

1. User Guide - https://docs.bokeh.org/en/latest/docs/user_guide.html
2. Reference - https://docs.bokeh.org/en/latest/docs/reference.html
3. Documentation spelling and formatting - https://github.com/bokeh/bokeh/issues/8448
4. Bokeh Examples - https://github.com/bokeh/bokeh/tree/master/examples
5. Include example code of PolyEditTool and PolyDrawTool Docs - https://github.com/bokeh/bokeh/issues/9962
6. Add mention of Themes to "Styling Visual Attributes" docs page - https://github.com/bokeh/bokeh/issues/9007
7. Reference Guide should link to Users Guide where appropriate. - https://github.com/bokeh/bokeh/issues/9363
8. Sphinx - https://www.sphinx-doc.org/en/master/
9. Vale - https://github.com/errata-ai/vale
10. Vale Linter - https://github.com/marketplace/actions/vale-linter