> I want to challenge implicit assumptions about the audience of technical writing.
I think this is the problem other people are picking up on. Implicit in the idea that you need special technical explanations targeted to women is some notion that women have difficulty with "regular" tutorials. What is that notion? Is there a gender bias to most technical explanations? If so, how does it work, and how is this different? Perhaps there is something, but it needs to be stated and applied.
Without making your "we need explanations specifically targeted to women" theory explicit and robust, you just come off as saying "women need tutorials, so I made you one", which is why it comes off as condescending. Worse, since the tutorial seems perfectly "normal", it's easy to think you're just name-checking a concern as intro boilerplate and then writing a totally unrelated thing about Clojure.
The thing is, it's good article about Clojure. It can stand on its own, and women will read it because it's useful and because they want to know about the language. Perhaps they do need a tutorial, but not because they're women.
> Is there a gender bias to most technical explanations? If so, how does it work, and how is this different?
There is a possible answer to this. I'm just thinking out loud here, but hear me out.
There is a huge gender gap when it comes to programming, as we are all well aware of. A lot of tutorials (even some of the more basic ones, I struggled a lot when trying to move on from "hello world", and "Animal -> Dog" style OOP into actual programming, and this tutorial seems to address that (I've not read it yet, so I hold my judgement).
If those two assumptions hold, then it could be argued that: due to the gender gap, we can assume that females who are starting from scratch may not have the base knowledge for "regular" tutorials to fit them properly.
Now: This may not be true. And usually I'm the first to argue that gender, race, etc. should have no impact on technical writing and knowledge sharing. However, nearly every other tutorial in the worlds body of knowledge is written gender neutral, and the gender gap remains.
That statement could be said to be conflating two issues; Somehow I don't feel like tutorial writing is the missing link to fix the gender gap in our industry. But it was interesting to think about, for me at least.
It's an interesting idea: that the real problem is that things are really tough for beginners now, and since women are more likely to be beginners, it hits them harder as a group. But if so, you'd also expect a chorus of young men complaining about their experience in tech too, which I just haven't heard much of. After all, even if women are disproportionally beginners, beginners are still disproportionally men. (Come to think of it, I've never heard a woman complain that all the tutorials suck either.) I'd be curious to hear otherwise, but my impression was that the state of online programming education options are the best they've ever been.
So I doubt your theory. And so it seems that either those tutorials have a more intrinsic gender bias (defensible but needs defended) or the problem has nothing to do with tutorials on the internet and has deeper and broader causes, which is my default position. Or, like you said:
> Somehow I don't feel like tutorial writing is the missing link to fix the gender gap in our industry.
The tutorials are the best they've ever been and the tutorials suck. Programming real world systems still involves a large amount of "suck it up" pedagogy.
I'm not sure what this has to do with gender/race/sexual preference disproportions...
I think this is the problem other people are picking up on. Implicit in the idea that you need special technical explanations targeted to women is some notion that women have difficulty with "regular" tutorials. What is that notion? Is there a gender bias to most technical explanations? If so, how does it work, and how is this different? Perhaps there is something, but it needs to be stated and applied.
Without making your "we need explanations specifically targeted to women" theory explicit and robust, you just come off as saying "women need tutorials, so I made you one", which is why it comes off as condescending. Worse, since the tutorial seems perfectly "normal", it's easy to think you're just name-checking a concern as intro boilerplate and then writing a totally unrelated thing about Clojure.
The thing is, it's good article about Clojure. It can stand on its own, and women will read it because it's useful and because they want to know about the language. Perhaps they do need a tutorial, but not because they're women.