As Mark notes in his answer, there is something of a chicken-and-egg problem here. We need more tech-writing questions to get more tech writers who will ask and answer more tech-writing questions. I answer the ones I see when I have something to add, and some others do too, but we we need more of that.
I think we need to develop this aspect of our scope both internally (educating our own users) and externally (promotion). We should do it in that order, so new users don't come here and have a bad experience because the users who happened to vote on a question didn't recognize a Javadoc question as on-topic because they saw code in the post.
Mark identified several categories of questions common on tech-writing mailing lists, with Mark's assessments. Here are my thoughts on each of them:
- How do I express this idea? (Closed as a "what to write" question.)
Our "what to write" close reason is nuanced. But the good news is that many questions can be fixed. "How do I write documentation about class inheritance?" sounds like "what to write" and thus would get closed, but audience analysis and technique questions are on-topic, so that question could be recast in one of the following ways and be a solid, workable question here:
How do I write documentation about a core concept (such as class inheritance in Java or select statements in SQL) for a variety of audience skill levels? If I simplify it for the beginners, intermediate readers might give up before realizing this isn't just going to be the "101" stuff. (Notice that class inheritance is now an example, not the question, and the focus is the actual problem, in this case a varied audience.)
Our programming interface uses multiple inheritance, so our users need to be especially careful to avoid creating conflicts. In our API reference documentation, where is the best place to explain this? Should we add a warning to every affected class page that links to an explanation, should we embed that explanation in every page so people will see it (but maybe it gets in the way when people are browsing the doc), or something else? (Here we've put the need to document something about inheritance into a specific context of a reader problem that we are trying to avoid.)
Our non-technical corporate overlords have told us to convert our project code from C++ to Java because we're the only department using C++ and they want everybody to be using the same tools. Our project relies heavily on certain features of C++, like multiple inheritance. I can't teach a business director to program, so how do I explain that it would be technically very difficult to do what they ask? (This is a mix between a technical-writing question and a persuasive-writing question. Again, notice that this version of the question provides some context about the audience and the specific need, not just "how do I write X?".)
Those are just examples off the top of my head, but I hope they illustrate the point: sometimes a "what to write" question isn't really a "what to write" question if we can dig down a little. The community should help the OP to provide these additional details so we can reopen the question (if closed) and answer it.
After writing all that I remembered How to start a technical book?, which is kind of similar.
- How do I make this tool produce this output or perform this operation? (Multiple close votes from bored novelists, No answers except advice to ask on a tool-specific forum because no one here uses tool X.)
This is a pure community-education matter. Those questions are on-topic. They might also be on-topic on some other site, but that doesn't matter -- if somebody chose to ask an on-topic question here, we should keep it, try to answer it, and not send it and its asker away. I say this partly because we should respect our own community and partly because we want that person to come here for his next question too.
If you close votes or comments redirecting the OP, please speak up. Educate the bored novelist, vote "leave open" in the review queue, vote to reopen if it was closed, raise the issue in chat or on meta, or whatever else you can do to get (or keep) the question open so people can answer it.
If you know of people who can answer it, like people from that tool-specific mailing list, and if doing so wouldn't violate another community's rules, point out our question to them! Encourage others to come here to answer a question that you know they have the expertise to help with.
- My department is thinking about adopting tool X -- who here has used it and what did you think of it. (Probably the same as 2.)
"Who has used it and what did you think of it?" sounds primarily-opinion-based on any site. However, this is easily adjusted: ask about specific capabilities, ask for a comparison with your current tool, ask about adoption paths, etc.
Some examples in this ballpark:
- My boss is a jerk, what should I do about it? (Closed as not about writing and advice to ask on Workplace SE.)
That sounds about right. That question also sounds awfully subjective and opinion-based as asked. But I feel for the OP; I've had bosses like that too.
If the jerk-class behavior is about the person, management style, etc, then if the question could be refined it'd probably be workable on The Workplace. If the jerk-class behavior is actually rooted in the writing (I dunno, maybe a religious war about Oxford commas?), then it would be possible to ask a question here that would help the OP in his dispute with his jerk boss. That's a stretch, though, so unless the OP provides some indications that this is the case, we shouldn't expend too much effort on it. (If the OP has at least 20 rep, somebody might want to invite him into chat where we can rant about bosses past and present over a virtual beer in a friendly crowd.)
Tech writers are under-appreciated. What should I do to get more influence in my company. (Probably the same as 4, but I don't think it's happened yet.)
What is more important, writing ability or technical knowledge. (Ditto, or closed as primarily opinion based.)
I agree with your assessment, including that I don't think we've had something like #5. We have had viable career-path related questions, such as:
Let's all help people with tech-writing questions -- and other questions too, of course -- adjust them when needed to make them work well on this site, whether that's because of scope (the "what to write" questions) or because of being too subjective/opinion-based. Let's remember that questions, maybe even ones with code in them, can be on-topic here even if they're not about fiction. Let's do our best to welcome and encourage users, especially new users, with questions about all types of writing.
Our site will grow and strengthen through its diversity and breadth of expertise. Let's all do what we can to help.
