WOW! So many good arguments here.
It’s amazing to see how civilized this community is. If this were anywhere else on the web, I bet this discussion would certainly contain a few insults *high-fives everyone for being so awsome!*
I agree with @OBrienEditorial, I prefer hanging out on communities that are diverse (such as this one). You learn the most from people that don’t share your opinions.
I also agree with @johntheeditor. Your values will depend a lot on your target audience, and your processes will tend to be slower and more rigid as you grow.
Huge corporations have rigid processes for a reason. Usually the reason is achieving global scale.
Let me share a bit more of my own experience.
Me and my team work inside the engineering department, and create customer-facing documentation and training. The amount of internal documentation we produce is very limited.
I agree with @Sue. We are in the engineering department, because our product is a development platform, so even though our audience is external, they are developers, DBAs, and operations.
But here’s an interesting thing. The ultimate goal for our team is to “make our users proficient in 0 seconds”. So if we don’t have time for a feature, we prefer to use the few time we have helping the engineering team making a more usable product, than creating long docs.
Some teams that don’t interact with us so often, have an hard time understanding where we spend most of our time. This is the case of the support team.
So we need to do some browbags and share with them and other teams what we’re doing. Otherwise they see us as a documentation team that produces almost no documentation (so they feeling they get is that we’re not very good at our jobs )
The only point I disagree with @johntheeditor is that if you’re writing for DevOps, your users still get affected by typos. Lack of quality is not acceptable.
I’d argue the difference is that usually developers are hackers by nature, so even if they don’t understand the docs, they’ll try to find what they want by trial and error.
I also don’t want to blame tradicional tech writing for every frustrating, cumbersome, and slow process. I just want to raise awareness for some practices that might not be healthy for your users and for you (independently of where you stand on this old-school/new-school thing).
I want to raise awareness for the fact that rotten docs can sometimes be worse than no docs at all. And rotten docs usually appear because we decided to document everything to exhaustion, never thinking that two years from now, we’ll probably have the same (or fewer) resources to continue documenting new features, and maintaining old ones.
This topic is very important to me, because I’ve inherited lots of docs that my users tell me they don’t use. And after surveying they, I understood that it’s mostly due to bad experiences they had in the past, like:
- Documentation that was technically wrong;
- Outdated documentation;
- Documentation that was written but no one could find
- Documentation so cumbersome to use, that it was faster to experiment, and learn by trial and error.
I feel that attention to detail, style guides, good content organization are of paramount importance. But sometimes, we need to think strategically and think about why we have them in the first place.
And if we find that they are shackling us, and stopping us from delivering value to our customers, then we need to rethink them.
Finally, @Marya I wouldn’t stress too much about defining old-school/new-school. We need to deliver value to our end-users. As long as you do that, who cares about how you’re doing it?