RE: [Discuss-gnuradio] a call for a better wiki

[Long, Jeffrey P.]

Hi all-

I am relatively new to the list but I have been reading and watching
since 2005. Only recently have I been able to start using GNU radio to
do any "serious" work here at Mitre. The biggest issue that everyone
here complains of is documentation, so seeing the topic come up I had
to put my two cents in. While intro pages are good, and definitely
needed for people off the streets, the block level documentation is
also severely lacking. It is basically a painful process to string
something together for the first time. I consider myself a pretty
strong comm engineer(not so great programmer :) ) so I understand what
all the blocks do put I spend half or more of my time just trying to
figure out what the in's and out's are and the parameters and the
acceptable ranges. Some blocks are obviously better than others but it
seems like I am always reverting back to hunting through the c++ code
to figure it out.

For example somebody asked about this the other day and this is the
only documentation via Doxygen for a relatively complex algorithm.
***************************
Mueller and Müller (M&M) based clock recovery block with complex input,
complex output.
This implements the Mueller and Müller (M&M) discrete-time
error-tracking synchronizer. 

See "Digital Communication Receivers: Synchronization, Channel
Estimation and Signal Processing" by Heinrich Meyr, Marc Moeneclaey, &
Stefan Fechtel. ISBN 0-471-50275-8.
***************************
Pointing to the source theory is good but you still need to explain how
to use the block via its parameters etc and there are always
implementation specific details that will not be contained in the
original theory explanation.

Ideally documentation for a block should be something akin to the
matlab simulink documentation for a block. Obviously this is major
work, and I am the first one to admit that I hate documenting what I
build, but at some point if we want this platform to be embraced by the
common man (or woman) good documentation is a must. 

Perhaps a user editable wiki is the way to go to help cut down on the
amount of work. Eventually stuff would get pretty good, theoretically.
Anyways, just a thought, or two. Sorry for rambling.

- Jeff Long


 

-----Original Message-----
From: address@hidden
[mailto:address@hidden On Behalf Of
George Nychis
Sent: Friday, March 21, 2008 11:49 AM
To: Greg Troxel
Cc: Eric Blossom; address@hidden
Subject: Re: [Discuss-gnuradio] a call for a better wiki



Greg Troxel wrote:
> My take is that after we have some content, and it becomes too much
to
> be listed on the front page, then it will make sense to have more
> organized intro pages.
> 
> 

Right, or the better we organize the intro pages the easier it is to
see 
what kind of documentation we want and what is missing.

Personally, I think the how to build a block and exploring gnu radio 
guides should be integrated into the wiki as a start.  They should be 
broken down to be much less daunting, and by having them in the wiki we

can actually edit them :)  For example, they are a bit out of date with

flow_graph and friends gone, but only Eric has the key.

I really think that each of these guides could be broken down into 
multiple wiki pages to make them a bit more readable.

- George


_______________________________________________
Discuss-gnuradio mailing list
address@hidden
http://lists.gnu.org/mailman/listinfo/discuss-gnuradio