Re: How can we decrease the cognitive overhead for contributors?

[Ekaitz Zarraga <ekaitz@elenq.tech>]

Hi,

> This definitely falls into the IDE tooling issue that I complained about
> a bunch of times. There seems to be a reality distortion field around
> Lisp that makes some users believe that s-expressions automatically lead
> to a good IDE experience. And yet, Java IDEs have had automatic import
> management for at least 15 years (around the time I first used Eclipse),
> but Guile still doesn't have anything of the sort.
> It looks like the only way to move forward is for people to share these
> helper scripts they've been using and forging them into a consistent
> developer environment, maybe based on Guile Studio. Hopefully I can
> make some contributions towards such a project.

I fully agree with this. I'd also add that everything seems to be emacs
focused and not being an emacs user is kind of an extra barrier for people.
(I'm not an emacs user)

>                                       Lots of important use cases that
> Guix could serve are ignored because the people who need them are not
> represented in our community and/or they can't contribute and no one is
> able/willing to write code for them.

Yes, and even if you manage to write something yourself, many times you
get now answer to your patches because no one else is interested on what
you did. It's perfectly understandable but also discouraging.

Example: I wanted to push Zig support in guix a while ago. Made a build
system and got no answer. <https://issues.guix.gnu.org/60889#3>
The feeling here is that the code proposed is not good enough, but I don't
know how to improve it so I'm stuck. It would be great to feel comfortable
enough with the code to be sure that it can be merged, but I can't find
the resources to make it better. If it was clearer or if it was easier
both sides, maintainers and contributors, would be more effective and
happier.

> > * It's OK to make lots of mistakes
> > 
> > The people who have reviewed my code have been generous both with their
> > time and fixing my mistakes and then applying. Maybe this model is OK? I
> > still feel guilty every time a reviewer has to correct an oversight I've
> > made. I also want to become a committer, but I don't know how that would
> > work if I'm regularly making mistakes. Obviously people would still be
> > reviewing my commits, but presumably a committer should not regularly be
> > making mistakes.

Exactly my feeling. And I've been working with Guix for a while...

> In a sense I agree with this, but if mistakes are this easy to make,
> then I think something is wrong with the project, not with the
> contributor. Instead of making people learn tightrope walking, maybe we
> should be building actual bridges.
> Guix actually fares pretty well in this regard compared to some other
> projects I tried contributing to (stares at Plan 9), but there is
> still a lot of knowledge that experienced developers take for granted
> and don't actually document. Writing new packages is mostly documented
> well, but as soon as something breaks, you are thrown into the deep end,
> having to dissect logs, bisect commit ranges, learn strace, gdb (which
> still doesn't work well on Guix), learn how to compile packages with
> debug info (and actually waste some more CPU time and IO on rebuilding a
> package you already have), learn how to adapt docs from other distros,
> etc, etc, etc.
> I've been trying to document these at least for myself, but haven't yet
> had time to put them together into something others could read.

"As soon as *anything* breaks everything starts to fall apart" is a feeling
I also have a lot. Many things in my system are poorly configured because
I simply can't figure out how to fix. Default things work great, but when
something doesn't you are exposed to a great complexity, there's almost
no midpoint.

Specially, some services feel like nobody use them because they have almost
no options to be configured and there are no examples out there.

I have to say it got better in recent months. We are doing achievements in
this area, which is great.

> By the way, that's another issue. Using a TeX based document format for
> the docs is, uuuh, maybe not the best idea. Info is a pretty okayish
> documentation reader, but it's a relatively big barrier to entry
> compared to what you need to know to make a small edit to the Arch wiki.
> This way mostly just experienced contributors write docs, not the
> users who just want to document how they made some weird use case
> possible.

Again, I'd say this is because of emacs, again. It's not that bad, because you
can use the website, too, but collaboration in the manual is a little bit
daunting.

These are my five cents.

Cheers,
Ekaitz