First, let me get on the same page about your parent comment:
> A lot of technical writers focus on the style of the text. For example, I've seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization.
In general I agree that there are some technical writers who focus way too much on style. I also think that the list of practices that you described --- usability editing your docs, using a CI system and importing sections of the code samples into the docs to ensure that they're always working, being politically forceful about making sure that docs are treated as part of the core product and not an afterthought --- are all great practices. I agree that the practices you described should be established first before any debates about style.
Moving on, I emphatically disagree that minimalist and constructivist instruction are "style" considerations.
Style considerations are arbitrary decisions that you consistently follow in order to convey a sense of professionalism. In your first comment you provided a perfect example of a style consideration: title capitalization (e.g. whether to format your title like this "How to debug your code" or like this "How To Debug Your Code"). If we A/B tested a document to see if there was any change in user success rate based on title capitalization, there would be no difference.
Minimalist and constructivist instruction are guidelines on how to create effective instruction. For example, the minimalist guideline to explain how to recover from errors is a hugely valuable practice which is extremely obvious once you are exposed to the idea, but is somehow a practice that many forget to do.
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.
Avoiding passive voice is another example of something that may seem like a style consideration but actually goes a long way towards making your communication much more effective. The problem with the passive voice is that it often makes the subject of an action ambiguous. For example if you write "the script is updated" it's not clear who updates the script. If it's something that the user needs to do, it's much better to say "you need to update the script". If the user reads the passive phrasing "the script is updated" and they don't understand that they need to take an action, that's the potential difference between user success and failure.
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". This is the equivalent of saying "most software engineers are code monkeys with no social skills" and it's really damaging to the credibility of my industry. But I do agree that there are some who focus too much on that BS and you have my word that I'm trying to rid my industry of that bad habit.
> 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.
> A lot of technical writers focus on the style of the text. For example, I've seen tech writers have long discussions (more than 3 hour-long meetings) about title capitalization in our organization.
In general I agree that there are some technical writers who focus way too much on style. I also think that the list of practices that you described --- usability editing your docs, using a CI system and importing sections of the code samples into the docs to ensure that they're always working, being politically forceful about making sure that docs are treated as part of the core product and not an afterthought --- are all great practices. I agree that the practices you described should be established first before any debates about style.
Moving on, I emphatically disagree that minimalist and constructivist instruction are "style" considerations.
Style considerations are arbitrary decisions that you consistently follow in order to convey a sense of professionalism. In your first comment you provided a perfect example of a style consideration: title capitalization (e.g. whether to format your title like this "How to debug your code" or like this "How To Debug Your Code"). If we A/B tested a document to see if there was any change in user success rate based on title capitalization, there would be no difference.
Minimalist and constructivist instruction are guidelines on how to create effective instruction. For example, the minimalist guideline to explain how to recover from errors is a hugely valuable practice which is extremely obvious once you are exposed to the idea, but is somehow a practice that many forget to do.
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.
Avoiding passive voice is another example of something that may seem like a style consideration but actually goes a long way towards making your communication much more effective. The problem with the passive voice is that it often makes the subject of an action ambiguous. For example if you write "the script is updated" it's not clear who updates the script. If it's something that the user needs to do, it's much better to say "you need to update the script". If the user reads the passive phrasing "the script is updated" and they don't understand that they need to take an action, that's the potential difference between user success and failure.
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". This is the equivalent of saying "most software engineers are code monkeys with no social skills" and it's really damaging to the credibility of my industry. But I do agree that there are some who focus too much on that BS and you have my word that I'm trying to rid my industry of that bad habit.