Editing Season of Docs Proposal

Jump to: navigation, search

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision Your text
Line 12: 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?
  
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.
+
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.
  
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!
 
+
Your project’s scope
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 ===

Please note that all contributions to GNU Radio are considered to be released under the Creative Commons Attribution-ShareAlike (see GNU Radio:Copyrights for details). If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource. Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel | Editing help (opens in new window)