Hi all,
The more I look at our wiki, the more of a problem I think there is.
Yes, I understand WE are the creators of the wiki since it’s shared, but
I think that it could really use an overhaul with some guidance.
The common argument is that the code is documented, I think this is a
good argument in some situations, but there is an overall lack of high
level documentation. For instance, what tools are there for spectrum
analysis? How can you simulate the channel? What is GNU Radio + USRP’s
bandwidth? How can you use octave with GNU Radio? What PHY layers are
there? What applications are there?
I think that Firas’ attempt to better build a manual for the code is
great, but GNU Radio is still lacking high level documentation. If
you’re not looking to build a new block, and you’re not looking to
install GNU Radio, you’re going to have to dig through a massive source
tree or ask on the list. This is why we get the same questions over and
over where we provide answers like “look at benchmark_tx.py” or “there’s
a ton of examples in the code.” Yes, there are a ton of examples, but
the size of the branch makes it very difficult for someone new to find
appropriate examples.
We get tons of “new to GNU Radio, where to start?” questions on the
mailing list because of this I think. They’ve obviously found the wiki
since the links to the mailing list are on there. The guides on the
wiki are a bit daunting.
Thoughts? I’d be willing to work on a new front page design on a wiki
subpage, that if we like we can continue to build upon and eventually
overwrite the current front page.
Then, as we get questions to the list we realize what kind of
documentation we’re missing. And instead of always repeating ourselves
on the list, it might be helpful to write the answer somewhere in the
wiki and then respond with that wiki link. It would seriously help
build the wiki.
On Fri, Mar 21, 2008 at 11:10:34AM -0400, George N. wrote:
How can you use octave with GNU Radio? What PHY layers are there? What
we’re missing. And instead of always repeating ourselves on the list, it
might be helpful to write the answer somewhere in the wiki and then respond
with that wiki link. It would seriously help build the wiki.
George, I agree with the part about the missing overview does.
However, I don’t think the problem’s really the front page, it’s the
stuff
that’s missing behind it. You could link to the not-yet-written
overview stuff from the Documentation: list on the main page.
If you’re game, why don’t you start on the “high level overview” or
“where to start” or whatever you’d like to call it.
Eric
Eric B. wrote:
George, I agree with the part about the missing overview does.
However, I don’t think the problem’s really the front page, it’s the stuff
that’s missing behind it. You could link to the not-yet-written
overview stuff from the Documentation: list on the main page.
If you’re game, why don’t you start on the “high level overview” or
“where to start” or whatever you’d like to call it.
Right, I didn’t mean so much that the front page is the major issue, but
more that it’s a start to branching out to more detailed documentation.
Like right now, if I were to write a simple guide on how to do signal
anylsis in GNU Radio, what would be the parent wiki page? The front
page? Or what if I wanted to document what PHYs are available, what
would be the parent wiki? There needs to be something better inviting
from the front page, as a start to branching out to more specific
documentation.
I’m not sure how we might want this structured, so I figured we might
start with the front page. The better the wiki is structured, the more
inviting it will be for people to add documentation. Right now, even
though I feel I’m pretty familiar with the wiki and GNU Radio, as I
think about making a wiki page I honestly have no clue where to actually
link it from.
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.
George N. wrote:
I’m not sure how we might want this structured, so I figured we might
start with the front page. The better the wiki is structured, the more
inviting it will be for people to add documentation. Right now, even
though I feel I’m pretty familiar with the wiki and GNU Radio, as I
think about making a wiki page I honestly have no clue where to actually
link it from.
So for example, we have the “Documentation:” heading… what kind of
things would we want under that to help document certain aspects of GNU
Radio? Like “How to use octave with GNU Radio” … “Doing signal
analysis with GNU Radio”
More of a what do we want there question, and how do we structure it to
be inviting to more documentation.
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.
Greg T. 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.
Here’s a new front page which gives a better understanding of what kind
of documentation I would like to see, and what I think is missing. The
layout is another issue. Everything I’m addressing is in the left
column.
http://gnuradio.org/trac/wiki/WikiStartNew
Brian had an interesting suggestion, using an image similar to that
found on the front of the Sklar book, which has a clickable block image
for each layer in the architecture and by clicking on it, you are taken
to a list of blocks available in that layer.
http://radio-1.ee.dal.ca/~ilow/4503/0130847887.jpg
So, if you click on channel, you would be given information about
simulating the channel in GNU Radio. It would take the place of my
“Available Features:” heading.
Hi,
The suggested new wiki page is a good step and adds something to the
projects. I just want to write this old famous words hoping to start a
view
to guide the new project users who might start contributing to the
project
itself soon after they understand it.
The words says, “Experience I cannot teach, I can only guide you”.
Best Regards,
Firas
View this message in context:
http://www.nabble.com/a-call-for-a-better-wiki-tp16200478p16208903.html
Sent from the GnuRadio mailing list archive at Nabble.com.
On Fri, Mar 21, 2008 at 12:57 PM, George N. [email protected] wrote:
Here’s a new front page which gives a better understanding of what kind
of documentation I would like to see, and what I think is missing. The
layout is another issue. Everything I’m addressing is in the left column.
http://gnuradio.org/trac/wiki/WikiStartNew
I really like the idea of improving the wiki and the sections that you
included for your mock up of the front page above . I fully agree with
your
initial post in that the list is hit with many “new” people who are
asking
the same questions (I definitely did when I first started so I
understand).
The sections you included, if well documented, would really help.
George N. wrote:
Brian had an interesting suggestion, using an image similar to that
found on the front of the Sklar book, which has a clickable block image
for each layer in the architecture and by clicking on it, you are taken
to a list of blocks available in that layer.
http://radio-1.ee.dal.ca/~ilow/4503/0130847887.jpg
What do people think of this idea?
The blocks in gnuradio need some kind of categorical hierarchy. Not
blks2, wxgui, gruimpl, gengen… More like sources, sinks, modulators,
encoders, filters…
We could manually compile a list of usable blocks that maps each block
to a category. Or hide the category information in the documentation of
each block, and extract it from the doxygen xml files.
Then you can generate a webpage or a cool interactive javascript thing.
And link each block to the doxygen page. That would be a very helpful
thing to have.
-Josh
Josh B. wrote:
thing to have.
-Josh
I definitely agree with this. They need to be broken down in to
functionality to make it even remotely easy to find the type of blocks
you’re looking for by searching through the code. Then we can break the
documentation up into these categories.
What categories do people think are a comprehensive list?
Even if we don’t break the code down into this structure now, because I
don’t know how difficult that will be to completely move everything
around, we can at least break it down nicely in the documentation.
On Sun, Mar 23, 2008 at 11:40:06AM -0400, George N. wrote:
Then you can generate a webpage or a cool interactive javascript thing.
What categories do people think are a comprehensive list?
Even if we don’t break the code down into this structure now, because I
don’t know how difficult that will be to completely move everything around,
we can at least break it down nicely in the documentation.
Guys,
There is currently a category list, and most blocks are currently
assigned to one of the categories in the list. I’m not attached to
the current list, and some of the blocks are definitely
miscategorized. Please feel free to propose a revised list and then
reclassify the blocks.
The list of categories is in
gnuradio-core/doc/other/group_defs.dox
The blocks are assigned to the groups by the
\ingroup
markup in their .h doxygen class comment.
The documentation categories are completely orthogonal to the
directory hierarchy, so there’s no reason to move stuff around to change
them.
See http://www.doxygen.org for docs.
Eric
On Mon, Mar 24, 2008 at 12:25:43AM -0400, Josh B. wrote:
Some quirks with using the current doxygen groups:
- The python based blocks (blks2 and wxgui) seem to be missing.
- Signal blocks and helper functions (gri stuff) are mixed into the same
group. Not that this is bad, but its not the same as having just a list of
signal blocks.
I agree this is probably wrong.
I think there ought to be a top-level category for gr_blocks, that
contains all the other block subcategories under it. The gri_ and
gr_fir_* stuff should not be under the block category.
- Some blocks are really specific and only used as a part of a bigger
signal block.
To start, we could make a wiki page that listed each major group and liked
to the doxygen group page. But a comprehensive list of just signal blocks,
that someone would actually use, maybe this would have to be manually
compiled.
Thoughts?
Let’s come to some kind of agreement on the category list, then edit
the headers of any miscategorized classes, then create the wiki page
linking to the updated docs.
The python stuff currently gets included in a kind of screwy
way. Somebody should take a look at it and sort it out. We may want
to consider generating the xml output, then filtering it to rename/fix
the python extracted docs so that they fit more naturally into the
hierarchy. I think you can feed the modified xml back into doxygen and
have it generate the html from that. It’s also likely that the docs
embedded in the python will need some work. Some of them have the
class and constructor docs conflated.
Eric
On 24/3/08 04:41, “Eric B.” [email protected] wrote:
<>
Let’s come to some kind of agreement on the category list, then edit
the headers of any miscategorized classes, then create the wiki page
linking to the updated docs.
I’m wondering if a TiddlyWiki might be a nice way to navigate the
documentation. So you’d have one ‘tiddler’ (Wiki item) per block and
with
navigation being non-linear could have multiple blocks from various
categories open at once.
http://www.tiddlywiki.com/
TiddlyWiki is also easily extensible via macros and plug-ins, and some
additional possibilities might be:
- Macros for searching for blocks
- A doxygen plug-in for importing data. Would need to look into this but
I
know there are plug-ins for other data sources, which might at least be
a
start.
- In the future generating python code. E.g. A templating plug-in is
under
development that is currently being used to generate static HTML output.
And as this would be realised as a single HTML file makes offline
viewing of
the documentation simple.
If of interest I’d be happy to look into this. I’m neither a doxygen nor
TiddlyWiki expert, but have access to the latter and might be a nice way
to
learn more about GNU Radio architecture.
Regards,
Andrew
Nifty!
Doxygen always surprises me. I have been building a category tree myself
for the blocks in grc:
http://gnuradio.org/trac/browser/grc/branches/grc_reloaded/src/grc_gnuradio/data/block_tree.xml
I will take a few tips from the doxygen groups (since they are a bit
more comprehensive). The main difference with the grc list is that the
list contains only signal blocks, and only signal blocks that can be
used in grc. Also some custom blocks.
Some quirks with using the current doxygen groups:
- The python based blocks (blks2 and wxgui) seem to be missing.
- Signal blocks and helper functions (gri stuff) are mixed into the
same group. Not that this is bad, but its not the same as having just a
list of signal blocks.
- Some blocks are really specific and only used as a part of a bigger
signal block.
To start, we could make a wiki page that listed each major group and
liked to the doxygen group page. But a comprehensive list of just signal
blocks, that someone would actually use, maybe this would have to be
manually compiled.
Thoughts?
-Josh
On Thu, May 01, 2008 at 01:31:08PM -0400, Steven C. wrote:
Apologies for the necromancy, but I would like to help by adding an
item or two to the FAQ section. How do I get a trac account?
-Steven
user: guest
passwd: gnuradio
Apologies for the necromancy, but I would like to help by adding an
item or two to the FAQ section. How do I get a trac account?
-Steven
