Season of Docs 2020 Ideas Page
Bokeh is an interactive visualization library for modern web browsers. It provides elegant, concise construction of versatile graphics, and affords high-performance interactivity over large or streaming datasets. Bokeh can help anyone who would like to quickly and easily make interactive plots, dashboards, and data applications.
Season of Docs is a program by Google to foster collaboration between technical writers and open source projects. Writers work closely with mentors and community members on documentation projects, for a period of ~3 months. See the full timeline here.
Make sure to go through the technical writer guide and check your eligibility before proceeding.
Note: Season of Docs is different from Google Summer of Code. Season of Docs is not a training program and expects to pair experienced technical writers with OSS projects. If that's not you, but you'd still like to start contributing to Bokeh, we'd love to help you find general issues from our tracker to get started on outside of Season of Docs.
New contributors should look over the Bokeh Documentation site and contributing guidelines. The Documentation section of the Developers guide includes the style guide, some best practices and instructions for building the Bokeh documentation. Contributors are also expected to be familiar with the basics of git and GitHub.
Before tackling a bigger idea, it is advised to start with some "good first issues" which can be found here.
The Bokeh documentation comprises of the following:
- Reference guide auto generated by Sphinx
- Docstrings and Model help available from a Python interpreter
- Narrative documentation (also generated using Sphinx)
- Tutorials - Interactive Jupyter Notebooks on Binder
- Demos of applications built using Bokeh
- Examples and READMEs in the project repository
- Medium Blog
Important updates are also posted on Twitter.
Documentation tasks are maintained in the project's issue tracker using the 'docs' component tag. Bokeh follows a Issue -> PR workflow and contributors are encouraged to create relevant issues and discuss the task before submitting a PR. Elaborate ideas and new features can also be discussed with the core team on the support forums.
- Explore the Bokeh documentation and go through the technical writer guide thoroughly.
- Select a project (or a combination of projetcs) from the ideas given below that best fits your interests and skillset.
- Discuss your project ideas with the mentors. To do so, draft a proposal.
- Read the Season of Docs guide on creating an application and our thoughts on what you can include in it.
- You can use google docs to create the proposal.
- Share a link to your proposal with the mentors.
- Post the link as a comment on this Discourse topic: Season of Docs 2020 Proposals.
- The above topic is to record all proposals in one place. Discussion about individual proposals will take place on the google doc itslef.
- Submit the application form on the Season of Docs website in time (before 9th July, 2020).
You can think about the following while creating your proposal:
- Introduce yourself and share your experience with documentation, open source and technology. You can include your work samples, past open source contributions and relevant personal projects.
- Talk about your selected project, how you plan to implement it (timeline), what are the key elements, etc.
- Tell us why you wish to participate and what are your personal learning objectives.
Note:
- If you need more help or are stuck at any of the above steps, please feel free to contact the mentors anytime.
- You can also work on some small issues to understand Bokeh's contribution process.
You can reach out to the Bokeh core developers on the Slack channel for Season of Docs 2020 or Development Category of the Project Discourse.
Note: Remember to always follow the Code of Conduct. :)
The Bokeh project can work with one technical writer in 2020. The admins and mentors for this round are:
- Bryan Van de Ven (bryan@bokeh.org)
- Pavithra Eswaramoorthy (pavithraes@bokeh.org)
The following ideas are flexible. The final project may be a combination of one or more of these ideas. Applicants are encouraged to work with the mentors to create a custom project that best suits them.
level: Intermediate
category: Technical Writing
Bokeh is comprised of many Model objects which collectively define hundreds of typed property fields. Some properties have very good help strings, but many only have very brief or cursory descriptions. The task is to perform a full review and expand/improve the strings wherever necessary.
level: Beginner
category: Technical Writing
Bokeh publishes a gallery of examples to serve as a quick visual index into capabilities and to provide immediate access to sample code for users to get started. The Gallery would benefit from expansion of content and re-organization as well as improvements to the layout and presentation. The primary task is to implement content changes: add text, context and explanations to the examples. The additional task is to suggest a process for the structural changes.
level: Intermediate
category: UX Research
Bokeh web properties have not been reviewed for accessibility. The task is to evaluate the properties and to suggest areas and ways to improve. For example, we could find a way to allow creators to add a top-level description to a plot that a screen reader could find.
level: Intermediate
category: UX Research
The Bokeh documentation site is large and has grown organically over time. The overall information architecture of the docs has never been reviewed. The task is to asses the IA, implement changes that can be done immediately and create issues with update plans for changes that may require deprecations/longer cycles.
level: Beginner
category: UX Research
The Bokeh documentation can be improved to have extensive cross-referencing to help link gallery examples, reference docs, and the narrative user guide together.
level: Intermediate
category: New Feature
The Bokeh Documentation (and other properties) could benefit from the addition of metadata such a Open Graph and Structured Data. Adding these would afford rich previews on many common social media sites, forums, and Google search results. The task is to first add metadata manually to small sites such as bokeh.org and then develop Sphinx extensions to automate adding relevant metadata throughout the entire docs site docs.
If you are already familiar with Bokeh, and have your own idea that you would like to pursue, we are also open to consider things outside this list. But in that case your proposal should be fleshed out to a significant degree (enough to estimate a rough work plan).