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?

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:

Forums

Stack Overflow

Code Repositories

Project Hosting

GitHub

Coding Tutorials

Codeacademy

Recorded Video

YouTube

Vimeo

Live Event Announcements

Meetup

Lanyrd

Presentations and Slidedecks

Slideshare

Speaker Deck

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?

Changing the game

Inspired by a recent blog post, Startup Lessons from 17 Hard-Hitting Quotes in "Moneyball", I just watched the movie for the first time.

Now, I'm not a sports person.  This isn't the type of film I typically watch.  But, at least in my mind, "Moneyball" wasn't about sports. It was about changing the game.

In the movie, the general manager of the Oakland As, Billy Beane, finds himself with limited resources to build a team.  But rather than accepting that he'll have to build a sub-par team and lose, he sets his sights high and finds a way to create a different type of team than anyone's created before.

This is an enormously important message for technical communicators.  Because of the internet, we are literally drowning in content.  By the same token, technology is moving much faster than it ever has.  We can't possibly keep up with the pace of new technological developments, and new things to learn about.

Technical writing teams currently try to solve this problem by asking for more and more resources, and hiring as quickly as they can.  The problem with that approach is twofold.  One, it would impossible to keep up with the pace of content demands, even if we did have unlimited resources.  Two, as the democracy of the internet lends a voice to everyone who wants one, the skills we offer as technical writers are no longer unique, and they're certainly not as valuable as they once were.  Which means, in a nutshell, that our companies are not willing to give us unlimited resources.

So, we have to change the game.  We have to find a way to meet the content demands of the world as it is today.  And we have to do it given the resources we have.

There were a couple of speeches in Moneyball that really hit home for me, in this context.

In one scene, Billy is talking about what he wants to achieve with the team he's built.  He says, "I've been doing this game for a long time.  I'm not in it for a record...I want it to mean something."

That's how I feel about helping move the industry towards a collaborative model of content creation.  I'm not in it to win, or get rich.  I'm in it to change the game.  I'm in it to help the job that I love and the people that I care about continue to hold their value in the context of a new reality.

In another scene, someone who sees what Billy has accomplished tells Billy that whenever you try to make a change, you meet resistance from people who are entrenched in the way things are currently done because "it's threatening their livelihood, their jobs.  It's threatening the way that they do things.  And every time that happens, the people who are holding the reigns, with their hands on the switch, they go batshit crazy.  But anybody that's not tearing their team down and rebuilding it the way you did, they're dinosaurs."

That's the harsh reality of the tech writing industry.  There are a lot of technical writers who have been doing the exact same job for decades.  It's worked so far, so why should they change things up?  Especially when change requires learning new skills, and reaching out in uncomfortable ways.  Well, folks, I've got news for you.  Our jobs, as they are now, are going away.  So we can either adapt now, or find ourselves with increasingly less interesting and less lucrative jobs as the world around us changes.

I think the future of content is in collaboration.  That's where I'm going, and I intend to take as many people there with me as I can.  Who wants to come along for the ride?

How to build a website in ten easy steps

I recently stumbled through the process of creating a website for my new company.  I thought I'd consolidate my learnings into a blog post in case they're helpful to any of you.

1. Write down what you want to say.  Before you start designing anything, sit down with a Google doc and write down your marketing message.  Imagine you're telling your ideal customer what you can do to help her.  To cover your bases, answer the basic "who, what, when, where, why, and how" questions and let your story unfold from there.
2. Organize what you've written down into a logical collection of web pages.  Sort out what you want to say into a set of pages that makes sense.  
3. Purchase a template that basically gives you the architecture your content requires.  Alternately, if you are an uber-designer, you can design your own site. Or you can find a design for free somewhere on the internet.  I am not a designer, by any stretch of the imagination, but realize that a good design goes a long way towards an effective first impression, and wanted to minimize the time I spent hacking my content into a site that someone else designed.  That's easier with a template that's designed to be flexible and extensible.  Therefore, I purchased a template.
   Regardless of where your design comes from, make sure that the site is mobile-friendly.  (In other words, Flash is out.)  If you can find a good HTML5 design, that's your best bet.
   I did a lot of searching before I stumbled across ThemeForest, which is ultimately where I found the design for my site.  The templates they offer are well designed and competitively priced.
4. Add your content to the template; adding, subtracting, and moving things around as needed.  
5. Customize the site design using custom graphics and fonts.  This is not actually as difficult or expensive as it might sound. iStock Photo is a great resource for graphic art. Google WebFonts let you do amazing things with fonts. (You might notice that after this step, you've drastically departed from the template you originally purchased.  That's how you get a custom website out of a template someone else designed.)
6. Set up tracking so you can evaluate and optimize traffic to your site. Generate Google Webmaster Tools and Google Analytics tracking codes and include them on your pages, as explained on the linked sites.
7. Think of, and reserve, a reasonable domain name.  Good luck.  Finding a good domain name that hasn't already been reserved is next to impossible.
8. Find a web hosting provider and upload your site.  I chose Bluehost and have been happy with them.  Their customer service was helpful when I was having an FTP problem.
9. Set up domain-specific email and calendar accounts.  A domain-specific account is much more professional than a generic web account. Google Apps gives you the convenience of Gmail and Google Calendar for domain-specific accounts.  
10. Drive traffic to your site.  Use Search Engine Optimization best practices to drive organic traffic to your site, and paid advertisements to include your site in targeted ads.

Here's what I ended up with: DevComm: Engage Your Developers.  Comments and feedback welcome!

What other great website development resources do you know of?

Corporate Identity 101

A corporate identity has a few basic required components:

• Company name
  Don Dodge recently gave a good interview on choosing a company name.  I'll be the first to admit that the name I chose for my company, DevComm, is terrible.  In this case, my writer's mind is working against me.  I'm used to coming up with the perfect word out of an existing dictionary, not the perfect set of harmonious, meaningless characters.  I'm still working on it.
• Logo
  You can buy a generic logo from various websites and print companies, or you can have one custom designed.  I commissioned Rusa Vuong, a San Francisco-based designer, to create a custom logo for me.
• Business card
  Rusa also created my business card design.  I chose to electronically embed my contact information on the back of the card using a QR Code. Rusa generated the code using QRStuff.  If you want to go the simple route, you can get a standard business card design from many printers.
• Website
  This one's complex enough to merit its own post, which is coming soon.

Resources for starting a new company

As I set off down the path towards starting a new company, I realize that there are a lot of things that I don't yet know how to do.  I have lots of questions:

• Should I structure my company as a consulting company, or a product company?  Or both?
• Is it just me, or do I involve others?  If I involve others, in what capacity?
• What kind of business do I set up: Sole proprietorship? LLC? S-Corp?  C-Corp?  Anything in between?   When do I file the paperwork?
• What legal considerations do I need to be aware of?
• Do I need funding?  If so, what for?
• Should I fund this myself (what's known as "bootstrapping", I've come to find out) or seek venture capital?
• What's the difference between angel investors and and venture capitalists, and why would I seek out one over the other?
• How do I find a designer to help me set up a marketing presence, like a logo, website, business cards, etc?

I've run my own consulting company before, but it seems different this time; bigger, more real. I've also worked in several startups, but never at the beginning of the venture when all of these decisions are being made.  So this is essentially all new to me.

Although I certainly don't have all the answers yet, here are a couple of the resources I've found that have been helpful so far:

• YCombinator: A micro-financing / mentoring organization that helps a select group of startups develop a business model and seek funding.
• SCORE: An entrepreneurial support organization with local chapters around the US.  They give  useful classes on topics related to starting a business.  I've taken "Be a Successful Consultant" and "Legal Issues for Small Business.  They also offer free consulting services that give you the opportunity to get feedback from seasoned entrepreneurs.  I intend to take them up on that as soon as I've narrowed down my list of questions. SCORE tends to be pretty generic in terms of the types of business it consults on, so it's not so great for questions specific to creating a technology-related startup.
• SVForum: A more tech-focused advisory network, local to the Silicon Valley.  They sponsor panel-style discussions related to startup topics.  The panel is usually composed of seasoned tech entrepreneurs and VC investors.  I attended " New Venture Launch Fundamentals for 2012" and got a lot out of it.  This is also a great venue for networking and meeting people who are working on similar things.
• The Founder Institute: A tech startup support organization that offers a complete curriculum for creating a startup.  They have chapters around the world.  I haven't started reviewing their curriculum yet but the topics look promising.

What other resources do you know of that help entrepreneurs?  What advice would you give to someone just in the midst of starting a new venture?

Being deliberate about career choices

Hello!  Long time no talk.

As you may have noticed, I've been taking an extended break from, well, everything, including this blog.  It's been kind of fun to be suspended in time, and get a break from the day to day frenzy of commute - work - commute - hanging out with the kids - sleep - and repeat, punctuated by a flurry of errands and kid entertainment on the weekend.  To paraphrase a saying, when I was at Google, the days were long, but the years flew by.  Taking a breather from all of that has been wonderful.

It's been so precious to sit on the floor and play a game with my kids, and be fully present; not distracted by the latest crisis at work.  And to go out to dinner and a movie with my husband and talk about something other than how we'll juggle this week's busy schedule.  And to have the time to tackle my never-ending to-do list, which is finally starting to diminish.

The word seems to have gotten out that I'm no longer with Google, and I'm getting job offers on a regular basis. Most of the opportunities have been for roles that I've done in the past; tech writing, and leading doc teams.  It would be so easy to fall into another job like that.  And yet, I've resisted, because I want the next step in my career to be different.  If I wanted to do the same thing, I would have stayed at Google.

I put myself through college by cleaning houses and working the cosmetics counter at Walgreens.  I have a healthy appreciation for the luxury of having plentiful food on the table and good health insurance.  So every time I turn down a job opportunity I sort of mentally recoil in horror and ask myself what I'm thinking.

And yet... and yet.  What keeps me going is the sparkle in peoples' eyes when I tell them that I want to help companies do collaborative documentation and support.  The excitement in their voices, when they say "Yes, that's a great idea, and have you considered... "  Their hope, when they say "Wow, my company could really use something like that.  When will you have a solution in place?"

These opportunities are much less tangible than a funded headcount for a documentation manager, or a vetted need for a tech writer.  But they're surrounded by passion and opportunity and excitement, and by the potential of a new way of looking at the world.

No, I don't have all the answers yet.  I don't even have a guarantee that an answer exists, or that I'll be the person to figure it out.  But I do see the value of collaborative documentation, and I want to try to move the industry forward in a way that realizes that value.  I do know that every advancement I make, however little, might drastically change the way companies and customers interact with one another.  So it is that my plan remains to, deliberately, refocus my career towards building collaborative documentation solutions.

The next chapter of my career

Well, folks, the time has come for me to move on.  Today is my last day at Google.

After I eliminated my position, I got to thinking about what I want to do next.  I thought about going back to tech writing, and there was plenty of opportunity to do so at Google, but it didn't draw me in, like it has in the past.  I thought about managing a different type of team, but that didn't resonate with me either.  In short, there was just nothing at Google that called my name.

I'm a firm believer in choosing work that you can be passionate about.  We spend so much of our time at work.  Our job should be something that gets us out of bed in the morning with anticipation for the day to come.  Sure, not every day can be like that, but overall, we should be doing something we love.

I also believe that careers don't have to be linear.  For some, the right choice is to work in one place for a long time, becoming a deep expert in what they do, and climbing the ladder over time.  Others prefer to hop from startup to startup, engaging in the excitement of a new venture.  Still others prefer to contract, sometimes working 80 hours a week on an exciting job, and other times taking long vacations. Many of us encounter a combination of those situations over the course of our career.

Finally, I see skills as abstract entities that can be applied to the same job title, or can be repurposed for new and different roles.  I think that outlook will become increasingly necessary as personnel needs morph to accomodate an ever-more-quickly changing world.

So.  What's next for me?

I'm going to start my own company, helping organizations implement collaborative developer documentation.

The industry's changing.  We've seen it.  I've talked about it a bit in this blog, but here it is: Developers no longer go to the manual first when they get stuck.  They go to Google, and type in the problem or error code they're encountering.  More often than not, this leads them to a forum, a blog, or some other "non-official" resource.

"Official" documentation is still important.  Without an initial version of the docs that accompanies the API distribution, and explains how to set up the SDK, how to use the APIs, and gives some sample code, it would be impossible for developers to understand what the API is, and what it's meant to do.  That documentation can never be written by the community, because writing it requires close collaboration with the developers who created the API.

However, there's a long tail of documentation that is best written by the community.  For example: explanations of how to overcome obscure errors that occur only in certain environments, sample code that shows how to use the API for things it's very good at, but for which it wasn't intended to be used, and, sometimes, up to date translations of the official docs.

For one thing, this kind of information is best learned through trial and error by a large user base.  Even if a tech writer did nothing but use the APIs, she would never encounter errors that occur with a different development environment, software version combination, or operating system.  The community is working on a diverse set of environments, will encounter these errors, and can help each other overcome them.

Secondly, more people means more viewpoints, and more viewpoints can provide better documentation. The whole is greater than the sum of its parts.  A community of collaborators provides creativity and strategic thinking that can only come from the meeting of more than one mind.

There are already many tools that enable collaborative documentation, such as Mindtouch, MediaWiki, and SharePoint, among others.  However, these tools fall short of encouraging people to contribute their knowledge to the docs.  There's no incentive for them to do so.  I have some ideas for fixing that problem.

Another roadblock with collaborative docs is that the review process becomes a bottleneck.  It is not sustainable to have a single person, or even a few people, review all contributions.  I have some ideas for fixing that problem too.

So there you go: that's what excites me.  That's what pulls me out of bed in the morning, eager to find out what the new day holds.  And so, with a mixture of anticipation and sadness, I say goodbye to Google, and welcome the next chapter in my career.

Think through your career.  Does its flow resonate with you?  Are there threads that have resurfaced at various points in your career? What do you like best about what you're doing now?  What haven't you done yet that you hope to do in your lifetime?

The future of technical communication

For most of the history of technical communication, docs have been a megaphone that enable one-way declarations from tech writers to product users.  In many cases, tech writers still perceive docs in that way.

However, user behavior has diverged from this model.  Since web search became good and readily available, product users no longer exclusively rely on the official docs.  Now they listen to whatever the search engine deems to be the most reliable answer to their question.  Sometimes, this comes from the official docs.  More often than not, though, the most useful information comes from forums, blogs, YouTube, and more.

As tech writers, we're at a crossroads.  We can either ignore the fact that the world has changed, or we can embrace it and realize that docs are now a multi-way conversation, of which tech writers only have a single voice.  Our job is still to make the most of that voice, but it's also to facilitate the rest of the conversations and make them more accessible to users.

Two examples of sites that do a good job of this are:

• Instructables
• iFixit 

Both sites seamlessly merge different, related content sources, including docs, forum answers, photos, and video.

Contributor profiles are a major focus of both sites, and the contributions of each user combine to create a site-wide reputation for that user. iFixit has a particularly good algorithm for establishing and showcasing contributors' reputations.

For both sites, the interface for contributing content is quite easy to use, with WYSIWYG authoring environments and brief but useful inline guidance. The Instructables site has excellent guidance on how to write good content (although it would be nice if this page were easier to find.)

What are other important considerations for collaborative sites?  What are examples of your favorite sites?