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