On 01/16/2021 09:00 PM, Glen Langston wrote:
> Dear Marcus and all,
>
> Thanks for all your efforts. I really to appreciate all you've done.
>
> Best regards,
>
> Glen
We know you do, Glen.
Sometimes when you haven't been "inside the sausage factory" it can be a
bit hard to understand why things are
the way they are.
Heck, I've been involved with software development for longer than many
on this list have been alive (!!), and I myself find it
increasingly unpleasant to maintain a working installation of ANY
piece of software--let alone Gnu Radio. The inherent complexity
automatically means a wide/deep dependency graph, which inevitably
means much opportunity for nail-biting and hand-wringing,
and general addiction to benzodiazepines :)
>
>
>> 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
>>
>
No comments:
Post a Comment