Re: [Discuss-gnuradio] Why Isn't GNU Radio Used More? Docs?

[Patrick Strasser]

schrieb Marcus D. Leech am 2011-05-09 17:12:
> The documentation, as Tom observed, is disorganized and incomplete. 
> This is rather an inevitable result of a system that grows organically
> as it has--99% of the contributing participants are largely coders, and
> not so much document writers.

I don't think that "outsourcing" documentation from coders is the way to
go. It's the coders that know about the functionality. They also know
the rationale behind the creation a a certain part of the system and all
the implementation details: Why was this implemented in this way and not
another, what are the strengths, what is important to know, what would
be a dis-use of the component, etc.

Of course not every coder is a good User Documentation writer. This may
be because the coder would have problems to imagine a point of view
without all the details he already knows, or he/she is using the system
in a very special way, which would be quite different from the
mainstream use.

So I think the best situation would be to have the coders write API
documentation and document design decissions - this could be a text
document in the source tree, a blog post or a summary to a mailing list
discussion; it should last and be accessible. Then more usage-oriented
people with a broader, less detailed view create a users documentation.

IMO GNU Radio lacks a lot of low level docs and design docs. Referning
to the (undocumented) source code is not documentation.
That Howto is a good starter, but I think it does not fit the needs of
the average user: Putting blocks together that just work.

Sometimes one can find some glimpses of rationales of new features on
the mailing list, but in general my impression is that the future design
is decided by people off-scene.

Just my 2 €-Cent...

Regards

Patrick
-- 
Engineers motto: cheap, good, fast: choose any two
Patrick Strasser <patrick dot strasser at student dot tugraz dot at>
Student of Telemati_cs_, Techn. University Graz, Austria