User vs Developer Documentation

From GNU Radio
Revision as of 17:43, 7 March 2019 by 777arc (talk | contribs) (Created page with "How can we draw the line between our User Documentation (i.e. the one wiki page per block, and the usage manual) and the Developer Documentation (i.e. Doxygen docs)? '''User...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

How can we draw the line between our User Documentation (i.e. the one wiki page per block, and the usage manual) and the Developer Documentation (i.e. Doxygen docs)?

User Documentation

  1. Meant for users who are unlikely to ever look at the source code
  2. 99% of them are going to be using GRC to create flowgraphs
  3. Split up into two parts: the one-wiki-page-per-block and the usage manual (both will live in the Wiki)
  4. Each page will be about 1 block, and explain how to use that block and what each parameter means. There should be an example flowgraph.
  5. 99% of users don't care about a block's "make signature" or any of the under-the-hood functions
  6. The User Documentation is what would show up in GRC in the documentation tab, i.e. something much more user friendly than what currently shows up


Developer Documentation

  1. In this context, developers are those who are modifying GR source code, or just software-dev-oriented folks who take the time to read through code
  2. If they are reading through a block's code, they probably know how the block works at a high level, but are interested in programmatic details
  3. Mostly consists of documentation is that in-line with the code
  4. Can be viewed in the Doxygen manual or just directly while viewing code