Non-friendly documentation

I agree. I have fallen into your cycle myself.

I have too, of course, even though it’s also true that I’ve submitted a lot of documentation PRs for packages I don’t maintain. You certainly don’t have to (can’t) fix everything. To me this is mostly about distributing the expertise & workload in a way that accelerates the improvement of Julia as much as possible. And improving documentation—including harnessing the special gift that only newcomers can bring, which is their perspective as a newcomer—is a huge part of that.

And, in some places, items where not documented where I expected to find them.

When you have a lot to convey, putting the right information in the right spot is a hard (probably ill-defined) problem, though I don’t mean to imply that we can’t do better. To those who might be motivated to pitch in, let me post my new favorite link on writing documentation, shared with me by @c42f: https://documentation.divio.com/. It’s certainly a model I will follow the next time I sit down for a major documentation project.

8 Likes