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.