12

The majority of the site is taken up by questions about , making it unclear that is firmly on-topic here. While we've definitely seen more tech questions in recent months, I'd like to see even more. Getting more tech questions on the front page would help.

enter image description here

From the number of users following , I'd suggest that people are interested in this kind of content, we're just not giving it to them.

Also of relevance, there's currently a proposal on area 51 for tech writing, something that very much overlaps with this site. If this goes into public beta it'll compete directly with Writers. At the very least, we'll have to find a way to co-exist with a site whose scope is entirely within ours. (IMO, having the same question on more than one site is fine as long as the different sites address different aspects of it.)

If we want more technical writing activity on the front page, how can we be more encouraging and welcoming to tech writing questions? Writers is great at generating amazing answers, how can we apply that to technical writing questions?

  • As an outsider, part of the problem is that I've never seen a technical writing question hit the Hot Network Questions list. Instead it's always been questions about novels to which the answer is "Yes, you can break the rules, but you should only do it if you have a good reason.". If I wanted to ask about technical documentation, I'd try Software Engineering; for academic papers I'd try Academia (though I don't know if I'd get a good answer there). Writers is totally out-of-mind. – Jeffrey Bosboom Aug 12 '17 at 21:12
5

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:

  1. 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.

  1. 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.

  1. 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:

  1. 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.)

  1. 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.)

  2. 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.

  • 1
    Here's the thing about what to write questions, though. For fiction, there is tremendous liberty and the whole art of the think lies in deciding what to say and how to say it. For a novelist, answering a "what to write" question is , in doing the essence of the job for them. But for technical writing, there are, in very many cases, standard ways to say things that people should use as appropriate. Technical writing is not about originality or imagination, it is about efficient effective communication and not to allow what to write questions is simply not reasonable for this field. – Mark Baker Jul 23 '17 at 23:25
  • And further to the point, SO itself accepts large number of what are, in essence, what to write questions. There are standard best ways to code certain operation is different programming languages, and many many questions are asking what those are. Without those questions, and their answers, SO would be of much less value. Prohibiting what to write questions makes sense for fiction. It makes no sense for technical communication. – Mark Baker Jul 23 '17 at 23:27
  • And further to that point, a community is, in many ways, a group that can be governed by the same rules. Those who chafe at the rules will form their own community, as they should. This is, functionally, a community of fiction writers, and the rules are appropriate for that community. A community of technical writers would feel more comfortable with a different set of rules. SO has many sub-communities, divided by subject matter (languages) but with common rules. But I don't think one set of rules works for both fiction and tech comm, even if both are writing. – Mark Baker Jul 23 '17 at 23:31
  • @MarkBaker do you have examples of questions that you see as "what to write" that are otherwise viable, that don't require domain expertise in asynchronous programming or jet-engine repair or medical imaging or whatever? – Monica Cellio Jul 24 '17 at 0:22
  • No, what to write questions in technical communication always require domain expertise. That is one of the defining characteristics of tech comm and what makes it an awkward fit for a general writing site. Not that we are not accepting questions requiring domain knowledge for fiction either (writers.stackexchange.com/questions/29279/…). – Mark Baker Jul 24 '17 at 11:37
  • Then it's an awkward fit for Stack Exchange and its format, period -- unless by "technical communication" you mean "software documentation". The tech writer looking for help documenting the inner workings of a piece of advanced medical equipment is going to be hard-pressed to find his answers on an SE writing site, general or tech-specific. (He might find an answer on Health or Biology.) I don't see a lot of "what to write" questions on Techwrl. I'd expect more on API-writers (because it's specialized), but the list is basically dead. When I had a terminology question I went to Programmers. – Monica Cellio Jul 24 '17 at 12:44
  • Perhaps. One could argue (in fact I have) that Writers itself is an awkward fit for SE, since writing does not have the kind of small reusable testable algorithm questions (how to code) that form the bulk of SO. But sometimes a community can make itself it a format, as seems to happen here for fiction writers. But tech comm is a different community and I'm personally not seeing the fit here. (TechWhirl is a shadow of its former self, as are the STC lists as far as I can tell. A lot of tech comm discussion seems to be on LinkedIn groups these days,) – Mark Baker Jul 24 '17 at 18:10
  • Indeed, as a writer, I recognize that certain rhetorical patterns work well for some subjects and not for others. SE is a rhetorical pattern (a dynamic community based pattern, but a pattern none the less) and it works brilliantly for programming questions and for some other types of questions too, but maybe not for writing and if for writing, maybe not for technical writing. But then again, it might work for technical writing with a different community and a different set of community rules. – Mark Baker Jul 24 '17 at 18:14
  • Most of the 160+ SE sites are much more subjective than SO. Consider (off the top of my head) The Workplace, RPG, Puzzling, Parenting, Interpersonal Skills, Worldbuilding... – Monica Cellio Jul 24 '17 at 20:28
  • Agreed. Though I would say less repeatable and less testable than SO, because you can be subjective or objective about any question. But none of them are remotely as large or successful as SO, and I don't think any of them occupy the same king of the jungle position in their field that SO does, and I venture that none of them would exist if it were not for SO. And each accommodates to its imperfect fit in a different way. A tech writing site might need a different accommodation than a site for novelists, which is what Writers is de facto. – Mark Baker Jul 24 '17 at 20:40
2

Part of the issue may actually be solved by the other proposal on Area 51. The site scope may just be too broad to be able to cater to all niches fairly.

If one were to draw a mental diagram of the niches served by Writers.SE, you'll also find that writing for advertisement is not commonly addressed, and that overlap between the niches - while not unheard of - is uncommon at best. Writing for different purposes just really are very different crafts.

Scoping down may actually be good for us, allowing other SE sites to cater to the niches we cannot adequately support because of oversaturation by fiction.

Written by a copywriter who once dove headlong into fiction

1

Part of the problem is certainly that building an audience is a chicken and egg problem. There are only a handful of regulars here who are tech writers, so not a broad base of people to provide answers. I answer the ones I can, but many seem to wither on the vine for lack of anyone with the relevant experience.

The other issue we have is that our on-topic rules don't really fit technical communication well. I have spent decades on multiple tech writing forums, from TechWhirl, to various STC forums, to multiple LinkedIn tech comm groups. As far as I recall, the most common questions on those groups fall into these broad categories:

  1. How do I express this idea?

  2. How do I make this tool produce this output or perform this operation?

  3. My department is thinking about adopting tool X -- who here has used it and what did you think of it.

  4. My boss is a jerk, what should I do about it?

  5. Tech writers a underappreciated. What should I do to get more influence in my company.

  6. What is more important, writing ability or technical knowledge.

What happens to these type of questions on Writers today?

  1. Closed as a "what to write" question.

  2. Multiple close votes from bored novelists, No answers except advice to ask on a tool-specific forum because no one here uses tool X.

  3. Probably the same as 2.

  4. Closed as not about writing and advice to ask on Workplace SE.

  5. Probably the same as 4, but I don't think it's happened yet.

  6. Ditto, or closed as primarily opinion based.

I'm a supporter of the Documentation proposal on Area 51, not because I don't want to see tech comm questions here, but because the above seem to make it a very difficult thing to cultivate here.

If we seriously want to encourage tech writing questions here, therefore, I think we have to worry about more than how to get more such questions on the home page, we have to think about developing a set of rules and a culture that will be welcoming to tech writing questions and figure out how to attract people who can provide better answers.

  • The remedies to 2 and 3 are (a) for knowledgable people to reopen the questions and (b) to fix that "some users don't understand our scope" problem. I address the former when I see it and encourage others to as well, and I welcome suggestions about the latter. – Monica Cellio Jul 23 '17 at 3:10
  • My further thoughts didn't fit into a comment. :-) – Monica Cellio Jul 23 '17 at 20:36
  • 1
    @Mark, thanks for your thoughts on this. I'm keeping this in mind as questions get close votes, like this one. If you see tech writing questions like this, please feel free to submit edits or just flag them and the mods will try and do it. – Neil Fein Jul 27 '17 at 23:44

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .