Season of Docs Proposal: Difference between revisions

From GNU Radio
Jump to navigation Jump to search
No edit summary
 
(20 intermediate revisions by the same user not shown)
Line 1: Line 1:
Notes - See https://developers.google.com/season-of-docs/docs/org-proposal-template#project_budget for the template/guide
= Update User-Oriented Documentation Within Wiki - GNU Radio =
 
Accepted organizations will be announced on April 16, 2021 at 18:00 UTC.
 
= Update Block Documentation Within Wiki - GNU Radio =


== About our organization ==
== About our organization ==
Line 16: Line 12:


=== Your project’s problem ===
=== 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.
Regarding documentation, the major issue we struggle with is that GNU Radio not only has a learning curve in itself, but it also requires some level of knowledge of digital signal processing, wireless communications, and software-defined radio.  Sometimes it's tough to draw the line for where to explain a concept in GNU Radio's documentation, or refer the user to external resources. Currently, every block that comes with GNU Radio has it's own page on the Wiki where usage of that block is documented, similar to each function or class within an API having a separate page/section.  From within GRC, which is GNU Radio's GUI used to edit flowgraphs, each block has a documentation tab that links to these wiki pages, and in the future we plan to have these pages show up in a mini-browser window within GRC itself. 
 
What is currently lacking regarding the block's documentation mostly comes down to three things: 1) lacking consistency between blocks and 2) missing information or elements of the documentation, such as links to the source code, and 3) writing quality of the existing explanations. We know that any technical writer should be able to help with 3), but we believe even 1) and 2) can be part of our proposed documentation improvements.


The more ingredient information we have, the more useful GloriousPickle is to all of our users!
The impact of these improvements is fairly straightforward; if users are able to figure out how to use the blocks more easily, they will get more out of GNU Radio.  If a user goes to use a block and doesn't understand how one of the block parameters works, and our documentation does not give them answers, the only thing left is for them to actually look at the source of the block.  While this occurs many times, we hope that more casual users will never be forced to reference the source code.
Your project’s scope


=== 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.
As part of the Season of Docs, the part of our documentation that will get updated/improved all lives on the GNU Radio wiki, and it includes our user-oriented block documentation (block usage and other info), our tutorials, and our "usage manual" which is a series of pages for the components of GNU Radio that are not block-specific. We aren't deliberately ignoring any of these docs, in fact we have made huge improvements to them in the last year, but we think a technical writer will be able to provide significant value.  We have mainly been focused on the technical content, not the writing quality.  And we are a community consisting of folks across the globe, many of which do not speak English as their first language.


The GloriousPickle project (code-named PicklePlus) will:
The technical writer assigned to this Season of Docs project 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).
# Take some amount of time to become familiar with GNU Radio, perhaps via a few of our beginner tutorials
    Using the friction log as a guide for understanding the gaps in the documentation, create updated documentation for the top use cases.
# Look through our current documentation on the wiki, including block docs, tutorials, and the usage manual
    Create a quick “cheat sheet” to help contributors new to pull requests and GitHub to help them be able to use our process.
# Join the documentation channel on our Matrix, to chat with developers and learn about what each developer thinks are the current shortcomings of our documentation
    Incorporate feedback from documentation testers (volunteers in the project) and the wider GloriousPickle community.
# Review and improve the usage manual pages
    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.
# Review and improve a portion of our tutorials, perhaps while doing the tutorial themselves to learn more about GNU Radio
# Identify where in our block-specific docs there is room for improvement, and with any time left, improve the identified areas


Work that is out-of-scope for this project:
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.
# Anything related to the Doxygen documentation, which is developer-centric and is currently in a poor shape, but it's essentially just automatically generated from information in-line with the code, so it's still useful for the core developers who are actually working on GNU Radio code itself.
    This project will not create any GitHub tutorials; instead, the cheat sheet will link to existing material that is relevant and helpful.
# GNU Radio Companion (GRC) improvements
# Documentation part of any 3rd party Out of Tree Modules, because they are not maintained by the GNU Radio Project


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.
We have already identified two members of our leadership that will act as mentors for the technical writer; Marc and Barry. These are the two members of leadership that have been focused on improving our documentation over the last year or two.  In terms of an estimated time, it's tough to put a number on it, we believe we can use any amount of time we can get from a technical writer, although three months seems like a good amount of time.


=== Measuring your project’s success ===
=== Measuring your project’s success ===


How will you know that your new documentation has helped solve your problem? What metrics will you use, and how will you track them?
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.


GloriousPickle receives an average of ten pull requests a quarter to add or update new ingredients (tagged ‘ingredient’). The majority of these pull requests (>60%) are from previous contributors. We believe that this improved documentation will result in more pull requests and more pull requests from new contributors. Since most of our active contributors began by adding ingredients, we also think improving this documentation will result in more active contributors overall.
We will consider the project successful if, after publication of the new documentation:


We will track two metrics (number of ingredient-related pull requests and number of pull requests from new contributors) monthly after the documentation is published. We will also track the number of contributors who have made more than three contributions overall, starting quarterly after the documentation is published.
# The number of emails/messages related to our documentation lacking, on a monthly basis, decreases by at least 30%
 
# The users we ask to review the new documentation provide positive feedback
We would consider the project successful if, after publication of the new documentation:
 
    The number of ingredient-related pull requests increases by 20%
    The number of pull requests from new contributors increases by 15%
    The number of contributors who have made >3 contributions increases by 10% (beginning the quarter after the documentation is published)


== Project budget ==
== Project budget ==


=== General guidelines ===
All values in USD
 
 
    You can include your budget in your proposal, or as a separate link. If your budget is fewer than ten items, we recommend including it in your proposal.
    All budgets should be in US dollars. We expect grants to range from US$5000 to US$15000; if your project is outside of that range, please provide additional information to justify your budget.
    We expect the bulk of your budget (60-70% minimum) to be allocated to the technical writer working on your project. We recommend budgeting on a per-project basis wherever possible.
    We expect open source projects to use open source tools whenever possible; if your project absolutely requires funds for proprietary software licenses or support, please include a justification for the amount.
    Other possible expenses include:
        Design work to create branding, logos, templates, or other design assets for your documentation site
        Minimal amounts (<US$200) for project swag (t-shirts or stickers for your participants). If you use the Season of Docs logo, it must be accompanied by your project or organization logo or name. Your swag may not use the name Google.
        Minimal stipends for volunteers who take on considerable mentorship or guidance roles in the project (we recommend no more than $500 per volunteer, please)
        Downstream donations to other open source projects should be no more than 10% of your budget total.
    Include other budget items as needed, along with justification for the amount sought. Expense justifications should highlight how the expenditure will contribute to the success of the project as a whole.
 
=== Budget ===


{| class="wikitable"
{| class="wikitable"
|+ Caption: example table
|-
|-
! Budget item
! Budget item
Line 82: Line 60:
! Notes/justifications
! Notes/justifications
|-
|-
| Technical writer audit, update, test, and publish new documentation of  x y z
| Technical writer to work on improving and fixing holes in our block documentation on the wiki
| 5000.00
| $5,000.00
| 5000.00
| $5,000.00
|  
|  
|-
|-
| Volunteer stipends
| Volunteer stipends, who will take on considerable mentorship roles
| 1000.00
| $1,000.00
| 6000.00
| $6,000.00
| 2 volunteer stipends x 500 each
| 2 volunteer stipends x $500 each
|-
|-
| TOTAL
| TOTAL
|  
|  
| 6000.00
| $6,000.00
|  
|  
|}
|}
Line 100: Line 78:
=== Additional information ===
=== Additional information ===


Include here any additional information that is relevant to your proposal.
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.


    Previous experience with technical writers or documentation: If you or any of your mentors have worked with technical writers before, or have developed documentation, mention this in your application. Describe the documentation that you produced and the ways in which you worked with the technical writer. For example, describe any review processes that you used, or how the technical writer's skills were useful to your project. Explain how this previous experience may help you to work with a technical writer in Season of Docs.
=== Internal Notes ===


    Previous participation in Season of Docs, Google Summer of Code or others: If you or any of your mentors have taken part in Google Summer of Code or a similar program, mention this in your application. Describe your achievements in that program. Explain how this experience may influence the way you work in Season of Docs.
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.

Latest revision as of 02:36, 23 February 2021

Update User-Oriented 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

Regarding documentation, the major issue we struggle with is that GNU Radio not only has a learning curve in itself, but it also requires some level of knowledge of digital signal processing, wireless communications, and software-defined radio. Sometimes it's tough to draw the line for where to explain a concept in GNU Radio's documentation, or refer the user to external resources. Currently, every block that comes with GNU Radio has it's own page on the Wiki where usage of that block is documented, similar to each function or class within an API having a separate page/section. From within GRC, which is GNU Radio's GUI used to edit flowgraphs, each block has a documentation tab that links to these wiki pages, and in the future we plan to have these pages show up in a mini-browser window within GRC itself.

What is currently lacking regarding the block's documentation mostly comes down to three things: 1) lacking consistency between blocks and 2) missing information or elements of the documentation, such as links to the source code, and 3) writing quality of the existing explanations. We know that any technical writer should be able to help with 3), but we believe even 1) and 2) can be part of our proposed documentation improvements.

The impact of these improvements is fairly straightforward; if users are able to figure out how to use the blocks more easily, they will get more out of GNU Radio. If a user goes to use a block and doesn't understand how one of the block parameters works, and our documentation does not give them answers, the only thing left is for them to actually look at the source of the block. While this occurs many times, we hope that more casual users will never be forced to reference the source code.

Your project’s scope

As part of the Season of Docs, the part of our documentation that will get updated/improved all lives on the GNU Radio wiki, and it includes our user-oriented block documentation (block usage and other info), our tutorials, and our "usage manual" which is a series of pages for the components of GNU Radio that are not block-specific. We aren't deliberately ignoring any of these docs, in fact we have made huge improvements to them in the last year, but we think a technical writer will be able to provide significant value. We have mainly been focused on the technical content, not the writing quality. And we are a community consisting of folks across the globe, many of which do not speak English as their first language.

The technical writer assigned to this Season of Docs project will:

  1. Take some amount of time to become familiar with GNU Radio, perhaps via a few of our beginner tutorials
  2. Look through our current documentation on the wiki, including block docs, tutorials, and the usage manual
  3. Join the documentation channel on our Matrix, to chat with developers and learn about what each developer thinks are the current shortcomings of our documentation
  4. Review and improve the usage manual pages
  5. Review and improve a portion of our tutorials, perhaps while doing the tutorial themselves to learn more about GNU Radio
  6. Identify where in our block-specific docs there is room for improvement, and with any time left, improve the identified areas

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

  1. Anything related to the Doxygen documentation, which is developer-centric and is currently in a poor shape, but it's essentially just automatically generated from information in-line with the code, so it's still useful for the core developers who are actually working on GNU Radio code itself.
  2. GNU Radio Companion (GRC) improvements
  3. Documentation part of any 3rd party Out of Tree Modules, because they are not maintained by the GNU Radio Project

We have already identified two members of our leadership that will act as mentors for the technical writer; Marc and Barry. These are the two members of leadership that have been focused on improving our documentation over the last year or two. In terms of an estimated time, it's tough to put a number on it, we believe we can use any amount of time we can get from a technical writer, although three months seems like a good amount of time.

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.

Internal 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.