> To put it another way, if we A/B test a documentation set that follows minimalist or constructivist guidelines with a documentation set written by someone who doesn't understand those principles, I will wager money that the minimalist/constructivist doc set will lead to higher user success rates, however we agree to objectively measure that.
Sure. What I was saying is that if you do A/B testing of docs that are written in a non-minimalistic way with correct, functioning code, and docs written in the best style with code samples that do not work, the former will have more value and will generate more of the before-agreed metrics than the later. Consequently, focus on minimalism should come after focus on technical expertise, which is not my experience (and I would go as far to say that it's not the practise of something like 80% of the field).
> As a meta note I'd really appreciate if you didn't say "most technical writers focus too much on style" and instead would say something like "the technical writers I've worked with focus too much on style".
I did say that. I said:
- "... most TWs I've seen ..."
- "A lot of technical writers focus ..."
- "... I've seen tech writers have ..."
I'll grant that there's missing one "... I've seen" in the list above :). But, of course it's only my experience. I don't know tech writers at Google, for example, or Amazon.
> This is the equivalent of saying "most software engineers are code monkeys with no social skills"
Yes we're in agreement that usability editing your docs and building automated processes that ensure that docs stay usable over time are the #1 priority.
> What I was saying is that if you do A/B testing of docs that are written in a non-minimalistic way with correct, functioning code, and docs written in the best style with code samples that do not work, the former will have more value and will generate more of the before-agreed metrics than the later.
Yes, also in agreement here. Usable docs is the table stakes.
Sorry about putting words in your mouth! I must have got triggered and jumped the gun without being very careful about looking at the exact words you used.
Sure. What I was saying is that if you do A/B testing of docs that are written in a non-minimalistic way with correct, functioning code, and docs written in the best style with code samples that do not work, the former will have more value and will generate more of the before-agreed metrics than the later. Consequently, focus on minimalism should come after focus on technical expertise, which is not my experience (and I would go as far to say that it's not the practise of something like 80% of the field).
> As a meta note I'd really appreciate if you didn't say "most technical writers focus too much on style" and instead would say something like "the technical writers I've worked with focus too much on style".
I did say that. I said:
- "... most TWs I've seen ..."
- "A lot of technical writers focus ..."
- "... I've seen tech writers have ..."
I'll grant that there's missing one "... I've seen" in the list above :). But, of course it's only my experience. I don't know tech writers at Google, for example, or Amazon.
> This is the equivalent of saying "most software engineers are code monkeys with no social skills"
It's not because of the ad-hominem.