Thursday, April 12, 2012

Top 10 reasons why soft skills matter for writers

I recently participated in a discussion about a blog post on How to Find Good Programmer Writers.  One of the people I was chatting with there kindly illustrated for us why it is so important for tech writers to have soft skills, such as "humility, tenacity, and curiosity" (as Andrew Davis wrote in the original post.)

Soft skills are difficult to account for in the hiring process, but in some ways, they're more important than technical or writing skills.  Here are 10 reasons why.

  1. Writers are often brought in at the end of a project.  Therefore, they're often in the position of knowing less about the project than anyone else on the team, and having to ask the "dumb questions" to get up to speed.  A writer's job is to ask the dumb questions on behalf of the users . So if they don't have the humility to do that, then they can't effectively do their job.
  2. Also related to being brought in at the end of a project, writers are often under tight deadlines.  They need to be able to negotiate a reasonable amount of time to write quality documentation, even though the entire team is breathing down their necks and waiting on them to finish the docs so the product can be shipped.
  3. Writers need to be constantly learning new things.  Without curiosity, they have no motivation to stay fresh in their technical skills.
  4. Sometimes writers need to ask the same question five times, to three different people, in five different ways, before they truly understand the answer.  If they don't have the tenacity and curiosity to do this, they can't understand what they're writing well enough to explain it to someone else.
  5. Writing projects tend to be shorter-lived than other projects.  Consequently, writers change jobs and teams more often than many other professions.  They have to be able to effectively and quickly establish new relationships with their new teams.
  6. Writers are often working on cross-functional teams that, besides themselves, include engineering, project management, QA, user experience, and other professionals. As I saw in a recent (excellent) job posting, if they don't have the "ability to interact calmly and rationally with a variety of people under pressure without acting like a totally dysfunctional psycho asshole" they're toast.
  7. Writers are often last hired, and first fired.  This being the case already, it is unwise to add to the problem by pissing people off.
  8. Writers' work is always subject to review by one person, and often by multiple people.  They have to be able to calmly, gratefully, and gracefully accept feedback on their writing.
  9. Especially for APIs, but often for other software products, the docs are often one of the most visible aspects of the product.  At the same time, the docs are responsible for glossing over the less well-designed bits by explaining the hard parts of using them (even when, sometimes, the hard parts can't be explained away.)  Therefore, docs are subject to a lot of criticism.  Writers have to be able to gracefully, yet firmly, find the balance between holding their ground and accepting constructive criticism.
  10. In general, it's just more pleasant to work with nice people.
What other situations occur to you that require soft skills for writers?  What soft skills are particularly important?

Friday, April 6, 2012

Where's all the good developer content?

Outside of documentation, there are a lot of good developer resources out there.  Here are some of the best:


Code Repositories

Coding Tutorials

Recorded Video

Live Event Announcements

Presentations and Slidedecks

Any good collaborative developer site should include the highest quality relevant content from these sites.

What am I missing? What other great developer resources do you know about?