Reading the announcement post of a GNOME library that shall go unnamed:

“There is no documentation yet, but I’m slowly getting more and more tests added which can serve as examples in the mean time. Go read some code, it’s good for you.”


Can we please cancel this mentality?

· · Web · 9 · 7 · 24

(Don’t get me wrong, reading code is a great way to learn. But it’s no substitute for good documentation. And the mindset that only those who are willing to dive into your codebase are worthy to use your library is, well, exclusionary to say the least.)

@aral Little doubt it's still incomplete four years on.

@aral I think it goes both ways with #freeSoftware, neither the consumer nor the producer has too much time. I always rush out code too early, hoping it might catch on.It's because I am poor I guess. And not smart.


Yep. We need synthethis between the following two true but seemingly contradictory things:

1. Library developers, don't be like this, i.e. don't rely on others to go read source. It's not cool. I get that all open source is a precious gift and that you don't owe anyone to write docs but if you haven't written docs and no-one has contributed docs, at least please be cool about it instead of being superior about it.♥

2. OTOH, if you're in the position where the best solution is to read source, don't be afraid to do so. I wasted years of trepidation (in the nineties) that I could've spent being productive if I had started reading source earlier.
@aral I mean, tbh it was just created at the time, I don't think not having complete docs before 1.0 is an issue

@aral hmm at least there are *some* tests, which already makes the project stand out from the crowd somehow (and better late tests than « never tests », yes?).

Incidentally, documentation is another great way to debug one’s own mind while designing a piece of software, as if explaining how things should work makes flaws stand out like warts.

@aral in. my experience "go read the code" is code for "the code is so bad I can't even write a paragraph in a natural language summarizing how it works"

@aral just changing the last sentence to "I would totally appreciate help in creating documentation." would be better. Give people an in rather than booting them out.

@nigeldgreen @aral lol I interpreted this as “stop this mentality” however with cancel culture I can see how this line was interpreted differently 🤣

@aral Best line from my old boss: “if it’s not documented, it doesn’t exist”. I apply that to everything I do.


What mentality ?
The one of being demanding towards people working for free ?

Is he preventing you to add documentation to his project ?

@Iutech This mentality.

It’s cool to keep it. But we’ll never compete with proprietary crap as long as we have it.

Sign in to participate in the conversation
Aral’s Mastodon

This is my personal Mastodon.