Editing User vs Developer Documentation

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 3: Line 3:
 
'''User Documentation'''
 
'''User Documentation'''
  
* Meant for users who are unlikely to ever look at the source code
+
# Meant for users who are unlikely to ever look at the source code
* 99% of them are going to be using GRC to create flowgraphs
+
# 99% of them are going to be using GRC to create flowgraphs
* Split up into two parts: the one-wiki-page-per-block and the usage manual (both will live in the Wiki)
+
# Split up into two parts: the one-wiki-page-per-block and the usage manual (both will live in the Wiki)
* 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.  
+
# 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.  
* 99% of users don't care about a block's "make signature" or any of the under-the-hood functions, so none of that is mentioned
+
# 99% of users don't care about a block's "make signature" or any of the under-the-hood functions
* 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
+
# 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'''
 
'''Developer Documentation'''
* 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
+
# 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
* 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
+
# 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
* Mostly (or only?) consists of documentation is that in-line with the code
+
# Mostly consists of documentation is that in-line with the code
* Can be viewed in the Doxygen manual or just directly while viewing code
+
# Can be viewed in the Doxygen manual or just directly while viewing code
* The developer documentation is going to be much more code-oriented, and involve more details about the implementation of the block (i.e. the block's API)
+
# The developer documentation is going to be much more code-oriented, and involve more details about the implementation of the block
 
 
'''What Goes Where'''
 
* High level descriptions of what a block does should go in the user docs, not developer docs, because it's not tightly coupled to the code, and devs can always reference user docs
 
* Example flowgraph will be displayed in user docs, and if its a big complex flowgraph it should also be committed in-tree and linked to within developer docs
 
* Descriptions of each parameter will have to go in both, but the user docs will only include parameters exposed via GRC
 
* Any API-type descriptions will be in developer docs only
 

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)