User talk:Duggabe: Difference between revisions
No edit summary |
|||
| Line 14: | Line 14: | ||
* Computer programmer since 1962 | * Computer programmer since 1962 | ||
* Retired 2003 | * Retired 2003 | ||
* Started working on GNU Radio 2019 | |||
==What is GNU Radio== | ==What is GNU Radio== | ||
GNU Radio is a free and open-source software development toolkit that provides Digital Signal Processing blocks to implement Software Defined Radios. | GNU Radio is a free and open-source software development toolkit that provides Digital Signal Processing blocks to implement Software Defined Radios. It is an entirely volunteer organization with contributors from all over the world. | ||
==Why did I get involved?== | ==Why did I get involved?== | ||
| Line 22: | Line 23: | ||
==Learn by Doing== | ==Learn by Doing== | ||
* When I got involved, the switch to using a Wiki was new. Many of the blocks were just skeletons with no real content. For example, https://wiki.gnuradio.org/index.php?title=Cvsd_encoder is yet to be documented. | * When I got involved, the switch to using a Wiki was new. Many of the blocks were just skeletons with no real content. For example, https://wiki.gnuradio.org/index.php?title=Cvsd_encoder is yet to be documented after more than four years. | ||
** I had to learn to use [https://www.mediawiki.org/wiki/MediaWiki MediaWiki]. | ** I had to learn to use [https://www.mediawiki.org/wiki/MediaWiki MediaWiki]. | ||
** I had to learn what a block did before I could write about it! | ** I had to learn what a block did before I could write about it! | ||
** After the first year of working on them, I had done | ** After the first year of working on them, I had done over 150 blocks and written or updated about 10 tutorials. | ||
==Help others to Learn== | ==Help others to Learn== | ||
I have found that the best way to learn about a technical subject is to study a turorial about it. However, there were very few tutorials, and | I have found that the best way to learn about a technical subject is to study a turorial about it. However, there were very few tutorials, and the ones which existed were out of date because of newer software releases of GNU Radio. | ||
==Adopting a Style== | ==Adopting a Style== | ||
It was rather surprising to me that there was no formal guidance for the style of the Block Docs or for tutorials. As I started working on the Block Docs, I derived a skeleton format which covered all of the items I found in various blocks. That gave a consistent layout from one block to the next. | It was rather surprising to me that there was no formal guidance for the style of the Block Docs or for tutorials. As I started working on the Block Docs, I derived a skeleton format which covered all of the items I found in various blocks. That gave a consistent layout from one block to the next. I also got some guidance from my mentor at GNU Radio based on unwritten expectations of how a block should be documented. | ||
For the Tutorials, there was much more latitude to create / use my own style. My basic approach was to write for a beginner with only the Prerequisites as a background. Other than that, I used an "Assume nothing" approach. | For the Tutorials, there was much more latitude to create / use my own style. My basic approach was to write for a beginner with only the Prerequisites as a background. Other than that, I used an "Assume nothing" approach. | ||
==Some examples== | |||
One of my more popular tutorials is https://wiki.gnuradio.org/index.php?title=Simulation_example:_FSK Along with that, I wrote the Block Doc for the https://wiki.gnuradio.org/index.php?title=VCO which is the key block in generating the FSK signal. | |||
In doing my work on the documentation, I wanted to make sure that what I wrote actually worked. So for each of my blocks and example flowgraphs, I created and tested them before I published them. For several of them, I created a complete working system using SDR hardware to operate with an amateur radio station. For example, https://github.com/duggabe/gr-RTTY-basics implements an amateur radioteletype station. | |||
Revision as of 16:12, 18 September 2022
Tech writing presentation
This is a DRAFT.
Preparation
- GNU Radio Main Page
https://wiki.gnuradio.org/index.php/Main_Page
- A Newbie's Guide to the GNU Radio Universe
https://www.youtube.com/watch?v=uxAW-WzuNy0
Background
- Amateur radio operator since 1953
- Electrical Engineering degree 1961
- Computer programmer since 1962
- Retired 2003
- Started working on GNU Radio 2019
What is GNU Radio
GNU Radio is a free and open-source software development toolkit that provides Digital Signal Processing blocks to implement Software Defined Radios. It is an entirely volunteer organization with contributors from all over the world.
Why did I get involved?
I discovered GNU Radio when reading an amateur radio manual. I thought it was a fascinating concept to use software instead of hardware to create a radio. After reading the "discuss-gnuradio" mailing list for a while, I noticed a recurring topic of "GNU Radio documentation is terrible". Looking at it, I had to agree, and decided to do something about it.
Learn by Doing
- When I got involved, the switch to using a Wiki was new. Many of the blocks were just skeletons with no real content. For example, https://wiki.gnuradio.org/index.php?title=Cvsd_encoder is yet to be documented after more than four years.
- I had to learn to use MediaWiki.
- I had to learn what a block did before I could write about it!
- After the first year of working on them, I had done over 150 blocks and written or updated about 10 tutorials.
Help others to Learn
I have found that the best way to learn about a technical subject is to study a turorial about it. However, there were very few tutorials, and the ones which existed were out of date because of newer software releases of GNU Radio.
Adopting a Style
It was rather surprising to me that there was no formal guidance for the style of the Block Docs or for tutorials. As I started working on the Block Docs, I derived a skeleton format which covered all of the items I found in various blocks. That gave a consistent layout from one block to the next. I also got some guidance from my mentor at GNU Radio based on unwritten expectations of how a block should be documented.
For the Tutorials, there was much more latitude to create / use my own style. My basic approach was to write for a beginner with only the Prerequisites as a background. Other than that, I used an "Assume nothing" approach.
Some examples
One of my more popular tutorials is https://wiki.gnuradio.org/index.php?title=Simulation_example:_FSK Along with that, I wrote the Block Doc for the https://wiki.gnuradio.org/index.php?title=VCO which is the key block in generating the FSK signal.
In doing my work on the documentation, I wanted to make sure that what I wrote actually worked. So for each of my blocks and example flowgraphs, I created and tested them before I published them. For several of them, I created a complete working system using SDR hardware to operate with an amateur radio station. For example, https://github.com/duggabe/gr-RTTY-basics implements an amateur radioteletype station.