[Discuss-gnuradio] Wiki Page per Block Documentation

[Marc Lichtman]

Summary- we are looking for help creating our block documentation on the wiki, read below for more info about it, but if you want to just jump in, here are a list of blocks that are stubs - https://wiki.gnuradio.org/index.php/Category:Stub_Docs  and you can look at the FFT block as a guide- https://wiki.gnuradio.org/index.php/FFT

As you may have heard from the monthly calls, we are in the process of revamping our "User Documentation", i.e. docs meant for people using GNU Radio, not developing it.  The plan is to have 1 page per block, describing what the block does and how to use it, similar to NumPy's and MATLAB's documentation with 1 page per function.  We hope that if we make it quick and easy for people to make small modifications or additions to the docs, more people will help improve them. We have had very few changes to our doxygen/sphinx docs over the last few years.  PR's aren't hard to do, but they just represent a non-insignificant amount of effort/time to get a change made, especially for newer folks (who are the ones using these User Docs the most). 

We decided to start by just using the wiki, but it might be transitioned to something else down the road.  Eventually we will want these docs to be a pop-up within GRC, possibly a mini-browser window type thing.  Currently we just link to them at the top of the Documentation tab (in 3.8 at least).  The wiki page title for a given block is simply the block's label, which is what shows up in GRC.  And Google has been great about indexing all of these new pages, meaning the wiki page will be one of the first things to come up when a block name is googled, so we'll try to get them all in decent shape ASAP. 

Currently, every block has a wiki page, but a little less than half are "stubs" and have zero info in them.  To not be a stub, a page needs at a minimum a description of the block and list of parameters and what they do, which can be largely copied from the existing Doxygen docs.  Ideally, eventually, every block will also have an example flowgraph, and a link to the source code at the bottom.  And we hope that over time, people improve on them, as they use them in their flowgraphs.

Here are a list of blocks that still need to be filled out, please feel free to help, the goal is to have as many filled out as possible by grcon - https://wiki.gnuradio.org/index.php/Category:Stub_Docs   We have been using the FFT block has a guide/template for the others - https://wiki.gnuradio.org/index.php/FFT

Feel free to message me on Slack with any questions/comments! 

-Marc Lichtman