Re: stop making unneeded improvements

[Glen Langston]

Dear Marcus and all,

Thanks for all your efforts.  I really to appreciate all you’ve done.

Best regards,

Glen


> On Jan 16, 2021, at 8:30 PM, Marcus Müller <mmueller@gnuradio.org> wrote:
> 
> Hi!
> 
> On 17.01.21 00:56, KB3CS - Chris wrote:
> 
>> why does not in my mind figure just as prominently as GSoC: other
>> campaigns like GSoD or GSoGUI ? (does anyone actually need me to fill in
>> the definitions for those abbreviations?)
> 
> Well, the G in GSoC is "Google", not "GNU Radio": Google sponsors a
> reasonable pay for a summer for students to work on open source projects
> that apply for that kind of support.
> 
> The rules of that preclude documentation work, and we are usually in no
> situation to spend much money. We work on changing that, but there's
> never been significant funds to throw at a technical writer, and what's
> more: the best tech writer needs either extensive domain knowledge, or
> much close cooperation time with the tech people – and both are very
> real limiting factors!
> 
> We did have multiple GSoC projects on GUI work. In fact, most years we
> had one. Getting someone up to speed with the project, and the usage
> patterns of the same, then have them contribute a great, and closed
> piece of GUI is definitely a employee management challenge, and don't
> forget that while these students are paid to work days like a proper
> developer, that's not true for the mentors that are supposed to
> supervise and support them – that's just extra workload atop of our
> dayjobs, and other GNU Radio contributions.
>> i am now an elder veteran of much documentation and technical writing
>> and .. and .. and .. as one might expect after a lengthy and
>> wide-ranging career.
> 
> Is this going where I hope it is going?
> 
>> where is the sustained outreach to *today's* new promising up-and-coming
>> Instructors (for tutorials), Technical Writers (to expand descriptions
>> and elucidate and footnote), and Documentation Writers (answering at
>> every turn - what is this? what is that? why is this? where are the
>> 'knobs'? where are the 'connectors'?) 
>> oh, it's a matter of money, i hear someone saying.. is it? is it really?
> 
> Yes, it is.
> Also, our days have 24h, so I can either write, review, merge and
> maintain code, or cooperate with a documentation writer. We honestly
> wouldn't have the time to even "supervise" someone to spend the time
> we're paying them for...
> 
> Google even had a GSoD, literally as you recommended. Small catch: it
> was unpaid.
> 
> Barry has done wonders here: He's coming from a space systems
> background, he's extremely clever, and he's picking up all the
> documentation slack, in an extremely independent way. That is really,
> really, incredible luck for us. Same with Marc, who's been doing a mix
> of documentation, management, and SDR teaching. I mean, how unlikely is
> it to find *two* people who are willing to do that, out of the goodness
> of their heart?
> 
>> who passed the hat lately? a boot? a plate? a tip cup? something? where?
> 
> Good point! We've been organizationally in a bit of a suboptimal
> situation to receive extraneous funding, but so far our money came
> primarily from sponsorships of companies at GRCon. The students working
> on GSoC, as said, were paid directly by Google, who doesn't allow work
> that is primarily documentation.
> 
> With SETI, we are now (pretty freshly) in a much better place, as
> outreach (and that includes user-friendliness) are an official goal,
> which might make money from various places at least attainable.
> 
> We have companies who dedicate engineer's time to us – that is
> invaluable. Monetary contributions can be complicated for some
> companies; that's one of the reasons why many companies choose to
> sponsor GRCon: that's a controlling-friendly way of making an expense on
> something.
> We simply didn't have had a steady income that would allow us to sustain
> a tech writer's compensation. I honestly don't know whether that has
> changed – but with the organizational shift, GRCon'20 going online due
> to epidemic problems, and whatnot…
>> please do press on forward but do not fear to ask for what is needed.
> 
> We ask for workpower!
> You're a tech writer. We're an underdocumented project with a lack of
> tech writers who know the project a bit.
> 
> Currently, we're seeing *huge* improvements compared to the past based
> on what Marc Lichtmann and Barry Duggan have been doing. That is really
> impressive, but I know the time that costs.
> If you have an acute
> 
>> no matter what it seems might be the result of honestly asking for help
>> when and where needed.
> 
> I promise money is welcome, very much so. I honestly don't know what
> kind of tax-deductible things we can offer. That's for someone else to
> explain!
> But, even more so: we're suffering success. When you ask [1] github how
> many people forked GNU Radio (and most of them do that to modify it and
> contribute their code back), github tells you:
> 
> ""Woah, this network is huge! We’re showing only some of this network’s
> repositories.""
> 
> That means an immense amount of work literally flows into nothing but
> making everyone happy (which might be contrary to the interest of the
> fewer people who'd like GNU Radio to stay exactly like it was, it seems)
> in the sense of keeping it running for their machines, and adding
> support for their use cases. There's a lot of quality assurance work
> there; it's following through with things; there's people forming work
> groups, there's keeping the contact with our awesome software
> distribution friends, there's the politics of keeping multiple parties
> somewhat happy when there's conflicts of interest, there's incoming and
> outgoing dependency trouble, there's release management…
> 
> I'd certainly like to institute a rule that says "you might only change
> that which you in turn document such that an outsider understands what
> it does", and "you can never get a feature upstreamed if it doesn't come
> with matlab-quality documentation", but I *do* _love_ that the project
> is not dead as a doornail; people simply couldn't contribute anymore.
> 
> So, the problem really is that the main driver for GNU Radio is
> technical people, doing technical things, often in their spare time, or
> paid under a contract with limited focus. Documentation is nothing I'd
> like to go sparse on, but honestly, the way a lot of user work flows are
> is "emergent", and changed, often after minor functional changes. It's
> often impossible for a developer to foresee what kind of documentation
> need things need. We, as the original developers, rarely find the time
> to go back after a year or two, when some patterns of usage have
> established themselves, and document things how they work then – if
> anything, we'd document how things are built and how we originally erred
> in assuming they *should* be used :)
> 
> GNU Radio has outgrown its original very much hacker user community and
> *is* a tool to bring SDR to the masses – but we have very little of the
> equipment needed to educate the masses. At the same time, it can do a
> lot of things that it couldn't do before, even if you're not an SDR
> veteran or a software developer by trade.
> A lot of the things that people complain about when it comes to
> documentation is either covered by "oh, yeah, that feels like basic
> computer usage to me, but then again I've been a developer for three
> fourths of my life", or "oh, yeah, that's a complex topic if you're new
> to signal processing or radio".
> Documenting these troubles away is *hard*, and also, probably a bit out
> of scope.
> 
> Of course, that leaves us with a lot of stuff that I fully agree needs
> to be documented. Again, Marc and Barry are working on these kinds of
> problems – if anyone has an hour to spare, I'm sure we can put that to
> good use.
> For example, read the GNU Radio Academy [2] with a critical eye. Do give
> constructive feedback (or fix problems right in place - it's a wiki for
> a reason!), enhance references, and so on.
> Same applies – even more so, because a one-shot contribution there can
> go a long way – to the block library documentation [3], which really is
> a monument to the dedication our small documentation team has – and
> actually, I often find, where they found time to write something longer,
> far beyond what you'll find in documentation in commercial software; the
> usual "oh, GNU Radio is soooo badly documented" is simply not that true
> anymore, in general. It's documented very well, where time by any means
> allowed for that.
> 
> So, even more than money, we look for people with the necessary
> experience and time to donate that – we could literally have millions in
> the bank account, and that wouldn't fix the issues at hand.
> 
> Best regards,
> Marcus
> 
> [1] https://github.com/gnuradio/gnuradio/network/members
> [2] https://wiki.gnuradio.org/index.php/Tutorials
> [3] https://wiki.gnuradio.org/index.php/Category:Block_Docs
>