Difference between revisions of "Season of Docs Proposal"

From GNU Radio
Jump to: navigation, search
(Measuring your project’s success)
(Measuring your project’s success)
Line 46: Line 46:
 
We get emails and messages in our Matrix chat channel on a monthly basis related to our documentation lacking information or being hard to use, and we do track these comments, mainly in our Documentation channel within Matrix.  So after the Google Season of Docs is finished, we will keep tracking these items, and then after a certain point we will look back to see if the activity has decreased.  As a second more formal method of tracking, once the season is finished, we will reach out to a handful of our users that are active on Matrix, and ask them to take a look at the new and improved documentation, to see what they like or dislike about it.
 
We get emails and messages in our Matrix chat channel on a monthly basis related to our documentation lacking information or being hard to use, and we do track these comments, mainly in our Documentation channel within Matrix.  So after the Google Season of Docs is finished, we will keep tracking these items, and then after a certain point we will look back to see if the activity has decreased.  As a second more formal method of tracking, once the season is finished, we will reach out to a handful of our users that are active on Matrix, and ask them to take a look at the new and improved documentation, to see what they like or dislike about it.
  
We would consider the project successful if, after publication of the new documentation:
+
We will consider the project successful if, after publication of the new documentation:
  
 
# The number of emails/messages related to our documentation lacking, on a monthly basis, decreases by at least 30%
 
# The number of emails/messages related to our documentation lacking, on a monthly basis, decreases by at least 30%

Revision as of 02:10, 23 February 2021

Notes - See https://developers.google.com/season-of-docs/docs/org-proposal-template#project_budget for the template/guide

Accepted organizations will be announced on April 16, 2021 at 18:00 UTC.

Update Block Documentation Within Wiki - GNU Radio

About our organization

In this section, tell us about your organization or project in a few short paragraphs. What problem does your project solve? Who are your users and contributors? How long has your organization or project been in existence? Give some context to help us understand why funding your proposal would create a positive impact in open source and the world.

GNU Radio (current version 1.2.3, first release in 2001) is a free & open-source software development toolkit that provides signal processing blocks to implement software radios. It can be used with readily-available low-cost external RF hardware to create software-defined radios, or without hardware in a simulation-like environment. It is widely used in research, industry, academia, government, and hobbyist environments to support both wireless communications research and real-world radio systems. The GNU Radio Project is run by the General Assembly, under the Articles of Association found here https://github.com/gnuradio/gr-governance/blob/main/aoa.md. The current leadership can be found on this page https://www.gnuradio.org/about/organization/.

GNU Radio makes it easy to share your work with others, through the use of custom blocks (a.k.a. Out of Tree Modules or OOTs), in fact we have an entire public directory of 3rd party OOTs, located at http://www.cgran.org. As an open source project, we have dozens of contributors on a monthly basis, and while it's tough to track the number of active users of our software, we estimate it in the tens of thousands, spread across the globe. Unfortunately, where our project has always had a weak point, is with the documentation. Because of the highly technical nature of digital signal processing, most of the effort has been focused on the functionality of our code, not necessarily usability. But in the recent year we have been trying to change that, through an overhaul of our user-focused documentation, found on our wiki. It is for these reasons we believe funding our proposal will create a positive impact in open source community and the world.

About your project

Your project’s problem

Tell us about the problem your project will help solve. Why is it important to your organization or project to solve this problem?

Users want to be able to add information about new spices and other ingredients (especially ingredients from non-European cuisines) to the GloriousPickle tool. Unfortunately, the process for adding this information is not documented well, which means potential contributors have to open an issue in the project to get help (or they just give up altogether). The process also assumes that contributors are already familiar with our pull request process and with GitHub, although many of our users are not professional developers.

The more ingredient information we have, the more useful GloriousPickle is to all of our users! Your project’s scope

Your project’s scope

Tell us about what documentation your organization will create, update, or improve. If some work is deliberately not being done, include that information as well. Include a time estimate, and whether you have already identified organization volunteers and a technical writer to work with your project.

The GloriousPickle project (code-named PicklePlus) will:

   Audit the existing documentation and create a friction log of the current documentation for the three top use cases (adding a new ingredient, adding a variant ingredient, and updating or correcting information about an ingredient).
   Using the friction log as a guide for understanding the gaps in the documentation, create updated documentation for the top use cases.
   Create a quick “cheat sheet” to help contributors new to pull requests and GitHub to help them be able to use our process.
   Incorporate feedback from documentation testers (volunteers in the project) and the wider GloriousPickle community.
   Work with the release team to update the documentation on the GloriousPickle site, and to create a process for keeping the documentation in sync with the update tool going forward.

Work that is out-of-scope for this project:

   This project will not create a process for cross-linking between different spellings or names for the same ingredient.
   This project will not create any GitHub tutorials; instead, the cheat sheet will link to existing material that is relevant and helpful.

We have two strong technical writing candidates for this project, and we estimate that this work will take three months to complete. The GloriousPickle PickleDocs SIG and @GloriousPicklePat (the core maintainer of the ingredient-adding API) have committed to supporting the project.

Measuring your project’s success

We get emails and messages in our Matrix chat channel on a monthly basis related to our documentation lacking information or being hard to use, and we do track these comments, mainly in our Documentation channel within Matrix. So after the Google Season of Docs is finished, we will keep tracking these items, and then after a certain point we will look back to see if the activity has decreased. As a second more formal method of tracking, once the season is finished, we will reach out to a handful of our users that are active on Matrix, and ask them to take a look at the new and improved documentation, to see what they like or dislike about it.

We will consider the project successful if, after publication of the new documentation:

  1. The number of emails/messages related to our documentation lacking, on a monthly basis, decreases by at least 30%
  2. The users we ask to review the new documentation provide positive feedback

Project budget

All values in USD

Budget item Amount Running Total Notes/justifications
Technical writer to work on improving and fixing holes in our block documentation on the wiki $5,000.00 $5,000.00
Volunteer stipends, who will take on considerable mentorship roles $1,000.00 $6,000.00 2 volunteer stipends x $500 each
TOTAL $6,000.00

Additional information

Both of our mentors, Marc and Barry, have developed documentation for GNU Radio, mainly the new user-oriented block documentation, as well as tutorials. One of our mentors, Marc, has worked with professional technical writers before, although not on the GNU Radio project, but he is familiar with the skill set and the limitations, and how interactions must work. This experience will help get the most use out of the technical writer assigned to our project.