bryevdv
commented
4 years ago Thanks @santos22 apologies for not specifying the preferred submission place up front, we will be more clear next time!
Closed santos22 closed 4 years ago
bryevdv
commented
4 years ago Thanks @santos22 apologies for not specifying the preferred submission place up front, we will be more clear next time!
Technical writing experience
Transformative technology for parents
Blog post detailing the technologies used to power Winnie.
https://winnie.com/blog/transformative-technology-for-parents
Plugging in to the Mattermost CLI
Blog post on my open source contribution to the Mattermost command line interface (CLI).
https://medium.com/@santosjs/plugging-in-to-the-mattermost-cli-8cdcef2bd1f6
Intuit gets Groovy
Blog post on the QuickBooks Engineering Blog summarizing my experience with the Groovy programming language.
https://quickbooks-engineering.intuit.com/intuit-gets-groovy-4c1f85f9ab4a
Project proposal
Open source organization name: Bokeh
Open source project name: Bokeh
The name of your proposed technical writing project: Improving the Documentation Experience for Bokeh Developers
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. You can find some examples inline in the documentation but a lot of examples are missing [4]. 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 them in the User Guide [5][6].
Lastly, there is a section in the User Guide that thoroughly covers adding new capabilities to Bokeh with inline extensions. This is not the case for pre-built extensions. A small section detailing pre-built extensions and some commands exists but there is no guidance on how to build and manage them [7].
Proposed documentation state
Automated spell checking
Vale Linter [8] is available as a GitHub Action [9]. It checks for spelling, repetition, and styling issues on every pull request. 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 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 respository should exist inline in the documentation.
A complete tutorial on pre-built Bokeh extensions
Bokeh is the standard when it comes to simple use cases for visualization. At the same time, advanced users with specific cases can add new capabilities with extensions. Bokeh provides the scaffolding for users to get started with pre-built extensions but the documentation for this scaffolding is lacking. A complete tutorial on setting up and creating pre-built extensions would make up for this. This tutorial would cover initializing and building extensions. It would also cover deploying and distributing them on npm, PiPy, and Anaconda.
Timeline
Pre-community bonding (present - 08/16)
Community bonding (08/17 - 09/13)
Week 1 (09/14 - 9/20)
Week 2 (09/21 - 09/27) Week 3 (09/28 - 10/04)
Week 4 (10/05 - 10/11) Week 5 (10/12 - 10/18)
Week 6 (10/19 - 10/25) Week 7 (10/26 - 11/01)
Week 8 (11/02 - 11/08)
Week 9 (11/09 - 11/15)
Week 10 (11/16 - 11/22)
Week 11 (11/23 - 11/29)
Week 12 (11/30 - 12/05)
Commitments
I live in the Pacific Daylight Time (PDT) timezone. I have a full-time job so most of my commitments to Season of Docs will be throughout the week in the mornings/evenings and on weekends. If this schedule does not work with Bokeh or any of the mentors, I am open to finding suitable times to collaborate and connect.
References