I have some clarification and apologies below, but first, in case you prefer PRs to debating: I sent a first PR (https://github.com/ensime/ensime.github.io/pull/190) to try to improve things. It’s not perfect, but if you’re open to the sort of changes I’m doing there, we have a chance of making things better, bit by bit. You wrote once:
> I will not merge any PRs to the website that prioritise practicalities over understanding.
I’m trying to make people understand what they’re doing while also making docs accessible. How much they should understand, and at which point in the docs, is an important question, but one I won’t tackle now.
Answering your post:
“We differ on our interpretation of the facts” is fine with me. I’m also fine with an open debate on the interpretation. I took “maybe what you’re not seeing” for a dismissal out of hand and reacted accordingly. I’m sorry if I misunderstood.
Having said that, I don’t claim I’m excellent at writing docs, sorry for being ambiguous. I only that I know the basics. I find writing docs harder than writing code. But those basics offer an alternative explanation for the confused users you see: many tried and failed looking at docs, and better docs could help. I’m not asking you to write those docs, but to consider this alternative explanation.