Earlier today I posted this question on programmers.stackexchange:

How can a manager best communicate software development best practices to junior and mid level staff?

My boss asked me this recently, and I was all set to give an elaborate answer about evidence based practices, effective use of code snippets, making content searchable, etc. Then I realized—these are just my opinions. I'm wasn't following my own advice. In order to talk authoritatively about what communications developers find effective, I need to ask other developers. So I bring this question to all of you.

Here's the scenario: Imagine you are a junior to mid level developer. A senior developer sends you an email with the subject, "Recommendations for best practices in [your key area of interest]." What would be contained in that document to make it most useful, interesting, and effective for you?

Key thoughts to consider:

  • When you read online documentation, how do you decide whether or not to trust it?
  • What format(s) are most useful (video, text, images, interactive tutorials?)
  • What qualities cause you to dismiss some piece of documentation?

This question is not concerned with client facing and public facing documentation. It is only concerned with internal training tools used within an organization.

The question was quickly closed for being too broad. One poster suggested that I edit the post to make it more specific. I'm not sure I see how this could get more specific, short of asking something fundamentally different, like "What style of technical writing performs best in laboratory comprehension tests?" which is not really even what I want to know.

One poster suggested that I post to workplace.stackexchange, but the post was removed from there as well for being "a poll." To be fair, I guess it is a poll but I'm not sure what I can do about that. Wouldn't any question related to this subject have to be a poll? There's many different ways to do documentation. It's almost as if the very subject matter of technical writing is entirely off limits, because there's so many ways to write that any question would be automatically too broad.

closed as off-topic by Scimonster, Martijn Pieters, Patrick Hofman, kiamlaluno, Aziz Shaikh Feb 24 '15 at 9:08

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "This question pertains only to a specific site in the Stack Exchange Network. Questions on Meta Stack Exchange should pertain to our network or software that drives it as a whole, within the guidelines defined in the help center. You should ask this question on the meta site where your concern originated." – Scimonster, Martijn Pieters, Patrick Hofman, kiamlaluno, Aziz Shaikh
If this question can be reworded to fit the rules in the help center, please edit the question.

  • 9
    If you say the question "ha[s] to be a poll," perhaps it's not a good fit for the Stack Exchange network at all. – Doorknob Feb 24 '15 at 1:34
  • Thanks for the reply @Doorknob, let me clarify. I don't accept that this is a poll. I'm not asking, "what's your favorite font?" It is possible to give a right or a wrong answer here, which is the important difference between this and an actual poll as most people would define the word. The reason I'm now asking for help, is that I can't seem to understand what stackexchange requires to not be considered a poll. – Matt Korostoff Feb 24 '15 at 1:55
  • 2
    It appears that you seem to have received an adequate explanation in the comments on your question; please explain what specifically you aren't understanding about the reasoning provided. "What would be contained in that document to make it most useful, interesting, and effective for you?" does indeed seem like a poll, and not an objectively answerable question. – Doorknob Feb 24 '15 at 2:06
  • In looking at the introductory part of the question "How can a manager best communicate...", I get the impression that this is too open ended to have one right or even a few right "best answers". When I think about answering the question, I can easily see how a series of answers from different users would end up being a collection of individual opinions, which ends up being a poll. – Suirtimed Feb 24 '15 at 2:10

If the question has to be a poll, it's not fit for Stack Exchange.

To prevent your question from being flagged and possibly removed, avoid asking subjective questions where … there is no actual problem to be solved: “I’m curious if other people feel like I do.”

emphasis mine.

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