Re: [Discuss-gnuradio] GNURadio scheduler behind the scene

[Marcus D. Leech]

On 12/26/2014 03:47 PM, Martin Braun wrote:


> Oh, but a written document with lots of pictures would surely be easier
> to understand, you might say? Well, first of all, that's highly
> subjective. Maybe, if we had someone highly skilled in technical
> writing, we might be able to make such a document. But again, it would
> be absurdly expensive, with questionable return of investement.
>
> Being a free software project, pointing people to the code is one of the
> few luxuries we have. What could be a more concise explanation of the
> source code than the code itself?
I'll augment what Martin said by observing that even in 
long-established, *commercial* code-bases, a
  "structured walk-through" document that gives a re-expressed in plain 
English and pictures overview is
  actually, in practice, a bit of a rarity.  In my 35+ years being 
involved in software development,
  I've only seen it on a few projects, and only on projects that had 
reached a development
  stagnation, where it was largely just in maint mode, which meant it 
was perhaps reasonable
  to invest in tech-writing resources to provide stable "internals" 
documentation.

Nothing is preventing anyone from writing such a document, and 
contributing it.  But since this is
  open-source, people largely work on what they *want* to work on. 
There's no paycheque
  (or threat of the lack of paycheque) hanging over peoples heads, 
forcing them to work on things
  they don't really want to work on.  And *most* developers aren't 
particularly-motivated tech-writers,
  and neither are they, for the most part, very good at it...


> In fact, following the "Don't Repeat Yourself" principle, it would be a
> bad idea to duplicate the structure in documentation. A high-level
> description of the scheduler is something else, of course, but that's
> why Tom made aforementioned presentation.
>
> What if the code is badly written and hard to parse? Again, that's
> subjective to a degree. But if something looks really badly written, or
> could use an additional comment, there's always the mighty tool called
> 'pull request'.
> We even fixed the spelling in one the scheduler's comments recently :)
>
> On top of reading the code, I suggest asking specific questions here
> (such as what does function x exactly do). This might encourage others
> to read the code and also we'll have more info in the mailing list archives.
>
> Cheers,
> M
>
>
>
>
> _______________________________________________
> Discuss-gnuradio mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/discuss-gnuradio