Musing about visionaries

I was most affected by Walter Isaacson's new biography of Steve Jobs. The book is a fascinating history of the personal computer, as well as a case study for how products are developed. I'm neither a Jobs fanboy nor a Jobs hater, and actually never paid much attention to him (even though, working in 'the biz', his name came up a lot). The Apple revolution sort of passed me by. I worked on Macs for a couple of years in the 90s and my main reaction was that they were underpowered. I'm simply too cheap to buy an iPhone or iPad, even though I recognize their value in opening up a new world of integrated data. Before reading the book, if you asked me to sum up the Steve Jobs' vision, I'd have said something like, "making things that are shiny and white".

The thing that struck me most about Isaacson's book is the advantage of having a visionary driving product development (and I now get it that Jobs was the ultimate visionary). In fact, since reading the book and thinking about places I've worked, many of them now seem utterly without vision - rudderless, or worse, propelled solely by interdepartmental politics and personal empire building. The exception is R&D departments run by a VP who has been on the team for a long time and who immerses himself in all the details of development. I have worked in a few companies that were run that way, and it seems an ideal structure - although none of them performed spectacularly. That lack of success may have come from the fact that R&D VPs tend to be developers who rise to the top, and possibly they bring with them too much reliance on a certain approach. As Alan Cooper would say, they are the inmate running the asylum.

Management visionaries are a double-edged sword. If they get it right, they're aces. But often they get it wrong, as Mike Lazaridis famously did when he decided that smartphone users would never embrace apps so the iPhone was not a threat to the BlackBerry. You can't expect visioinaries to succeed without quality inputs, which gets back to corporate structure: you need your visionary to be working with customers, feeling the bottom line, feeling the pain, feeling future trends. If your visionary is by nature an engineer, you might want to focus them on areas more suited to their mindset than things like consumer trends.

I was sympathetic to Jobs' frustration in getting his employees to do things his way. I wouldn't have wanted to experience his tantrums, but I can see why he had them. He never seemed to be able to get through to anyone - including Isaacson - that we need a fundamental change in our approach to developing products. Jobs’ employees wanted to create features while he wanted to create a user experience. He wasn't always right (or so it seems with hindsight), but his approach was.

In most companies it is a slow, difficult process to change the way people approach their work. So much is determined by corporate structure (eg you get very different results if the Doc department reports to Marketing or R&D). So much is determined by corporate culture (a bureaucratic mindset can deaden any initiative). Even when the people at the top try to change things, they don't always succeed, or succeed fast enough. To get back to the example of Mike Lazaridis: once he saw the light, was he ever successful in firing up his employees about superapps? I don't think so.

I don't want to say that visionaries are always at the top. Visionaries can exist at every level of employment, bringing that special something extra to whatever they're responsible for. The tragedy of mediocre managers is that they tend to feel threatened by visionaries and try to stomp out their initiative. It is also the tragedy of some corporate processes. In a DITA world where the writing process becomes a factory line of inputs, how do you handle writers who really get the user experience and have a vision for how to improve it? Sadly, the DITA revolution that is sweeping the industry seems determined to wipe out great writers. If doc management were able to recognize that trend, perhaps they could find ways to empower writers, even in the DITA paradigm. That would make a good talk for a CIDM conference: "The Effect of DITA on Writer Creativity, User Focus, and Empowerment - and How to Reverse It."

Tips for finding a tech writer job

I'm just going to bung down everything I can think of here, so some of it might be somewhat obvious. (And if you're wondering why I think I'm qualified to tell people how to find a job, the answer is that fortunately or unfortunately, I'm an expert!)

Form relationships with agencies
The ideal situation is to have agencies and headhunters contacting you about jobs, rather than you just applying for things. You should apply directly to agencies. For example, look up local sites for Procom, Ian Martin IT, Stratix, Tech Capital Partners, Bagg Technology Resources, Redwood Global, ProVision, Tundra Technical, or Silver Creek Partners. (Those are just some that I've worked with. There are tons of others, and a growing number in India.)

Sometimes a headhunter or agency will ask you in for a general interview. Depending on how you do, that could get you on their list. At the interview, the recruiter can give you all kinds of info about the current job market. They will also often make suggestions about your resume, and I recommend that you take their suggestions very seriously. They know.

To get on the list of headhunters, it helps to apply for lots of things, especially if the application goes to an agency.

If a headhunter or agency contacts you about a job, always respond. If you're not interested in the job, offer to tell your friends about it. If you’re a useful contact they’ll be more likely to keep you in mind.

Even when you're not interested in a job, always ask how much it pays. Finding out the going rates is really useful. Sometimes when asked what price you want, if you're out by more than a certain percentage the employer won’t negotiate.

Once you have a relationship, stay in touch. Send them resume updates. Let them know you're still looking. Connect with them on Linkedin.

Post your CV on job sites
Employers, agencies and headhunters regularly search through job sites such as Monster, Workopolis and Dice. (Here is a Canadian site for Dice: link)

Employers and recruiters search these sites electronically, so make sure you include all the keywords, software and skills that they will use when looking for someone for a job you want. Look at job ads to figure out what those words are. List all the tools you've used, even things you could pick up quickly. For example, if they have a requirement for a writer who knows Word and Excel, they might only pull CVs of writers who have those listed.

Modify your profile regularly. Adding or modifying a profile makes it more visible to employers.

Use Linkedin effectively
Some employers and agencies restrict searches to people who have three recommendations, so make sure you have at least three. And don't forget to add skills and get them endorsed.

Join Linkedin groups: they have interesting discussions, often have job postings, and are great ways to network. There are groups for former employees of many companies and many professional groups. Here are some tech writing groups: CIDM, Content Strategy, Documentation and Tech Writing Management, Information Design, Technical Publications & Documentation Managers Forum, Technical Writer in Action, Technical Writer Forum, Technical Writer of Writers, Technical Writer Worldwide, Technical Writing & Content Management, The Content Wrangler Community, User Experience, Users of Madcap Flare, Writing for Translation.

Google linkedin tips for more information specific to you.

Set up email alerts
Set up email alerts on a few sites so that you're notified of openings. No site has all job openings. Eleuta, Workopolis, Monster and Dice have services to email you with jobs that meet your criteria. I also really like indeed.com, which trolls corporate career pages.

You can set up multiple alerts from the same site; for example, sign up for tech writer jobs, journalism jobs, and information architect jobs.

Corporate Careers pages
Look for every careers page (corporate Careers pages, pages for levels of government, universities, careers lists, etc) that might someday have a job posting you'd be interested in, and favorite it in Internet Explorer. Every few days, run through the list of favorites and check every one.

Create a profile at every Careers page that allows it. It’s a pain and I don’t think I’ve ever been contacted by a company that asks for profiles, but you never know.

Bookmark other sites
Bookmark sites that might have job postings you're interested in, such as Southwestern Ontario STC, www.jobs.ca, Data Shaping, Charity Village, Mobile Dev Jobs, and the US STC job bank.

Check out kijiji and craigslist for your target areas. Check out temp agencies too. Temp agencies don’t tend to have great jobs but they could be a decent stopgap, as well as get your foot in the door of companies.

Contract work
In the last couple of years contract work has overtaken full-time employment, doubtless because of economic uncertainty. If you're married and have benefits through your partner, contract work can be very lucrative. But in any case, consider embracing contracting: educate yourself about how you can maximize your tax deductions, purchase health insurance and any other benefits, and so on. I spent two years living in fascinating places making a lot of money doing contract writing.

Here's a useful link for freelance and contract work: Freelancing: Are you ready>.

Online freelance work
It is possible to make a good living with online freelance work, although most job postings are scams (for example, their sole purpose is to attract traffic for clicks on ads). Online freelance work can include technical writing, proofreading, editing, ghost writing, and journalism (web pages, ezine articles, blog posts, product reviews, etc).

Volunteer
Volunteer to do work you enjoy, based on your career, hobbies, family situation, or whatever. It will give you something to put on your CV and talk about in an interview, as well as meet possibly useful contacts, get your foot in the door places, and keep your mind limber.

Career counselling
Go to the Careers Services department at your alma mater and ask for an appointment to get some advice. The University of Waterloo careers department has a boffo career consulting service. If you are a UW alumna, you get three free sessions; otherwise there's a modest fee. It is well, well worth it. You can sign up on this site, which also has lots of great info: UW career action.

More advice
There are zillions of online sources of advice, but here's a good one: STC job bootcamp.

My main piece of advice is to have a friend revise your resume. The biggest mistake on resumes is that people don't sell themselves sufficiently: an objective person can point out where you need to beef up your sales pitch, and how.

Other ideas? Please leave a comment!

Note: This post is an expanded version of a post I wrote for my other blog, here: Some tips for finding a job.

Just Say No

I once had a very wise doc manager who refused to allow the production of an install guide. When we found things in the install process that required documentation, he said, "Log a bug."

As a consequence, we had a great install process. And GREAT docs.

Thinking about writers

Being a good tech writer requires a lot of smarts and a lot of finesse. It's not just about knowing the authoring tools, learning the product, and knowing how to write.

It's understanding users, corporate priorities and the market.

It's learning which SMEs you can trust and which require double checking. It's learning how to motivate SMEs to help. It's learning how to work within other people's busy deadlines, to know when to push and when to hold back.

It's having the humility to accept other people's edits and the chutzpah to refuse other people's edits. It's having the tenacity to keep plugging away at something till you get it right, even though that process spans releases.

At your average tech writing job, it takes two years to become an expert in the product and customer base, form the necessary relationships, and learn the doc set. It is therefore important for companies to retain tech writers and to nurture them. Nurturing them means training, but it also means helping writers become more comfortable with responsibility - with honing and trusting their instincts.

All the supervision, editing and approval processes in the world won't make up for low quality writing. Unfortunately, all too often what holds writers back is all the supervision, editing and approval processes.

Writers have to "own" their areas of responsibility. Some writers won't do as good a job as others, but with time, training and nurturing, they'll get better. If possible, writers should see direct user feedback on their writing. Writers need to learn to have the reader perspective sitting in the back of their mind at all times. Every decision on terminology, wording, which information to include, topic length, and every other little thing should be made while thinking about the reader.

Some DITA CMSs include workflows that take doc ownership away from writers. I once had an editor who told me that our workflow was like a relay race - I as writer had prepared the first draft but then must pass the baton on to others. The editor didn't know anything about my users, the product or the market, and some of her edits created inaccuracies, but I had to fight for control of my content. That's the wrong way to operate.

Editors and information architects should not take responsibility away from writers. They can set guidelines and they can provide consulting services, but a writer has to be the expert in their own area. Otherwise it's just garbage in, garbage out.

Wait, you may say, what about hardware reference documentation that's essentially a list of specs? Well okay, there's an extreme end of publications that isn't really writing at all. But with tech writing, no matter how structured topics are or how complex a CMS is, at one end you have a writer and at the other end you have a reader. All the rest is secondary.

Writing documentation in an Agile environment

Agile was created by and for developers, and documentation does not fit naturally into its processes. Doc managers need to be proactive about integrating writing into the process. In my experience, doc departments take too passive a role.

Here are some of the difficulties with putting tech writers on Agile teams:

• For much of the Agile process, the software is not finished enough for writers to begin working on it. If writers start writing before a feature is complete, they may have to do a lot of rewrites. This can be a time waster. It can also lead to mistakes in the end process, especially if aspects of the feature are mentioned in several deliverables.
  
• Depending on the writing requirements of each Agile project, a writer might need to be part of multiple projects. I was once on seven active Agile projects at the same time. It's not feasible for a person to attend seven daily standup meetings, even if they're only 15 minutes each.
  
• Agile is designed to get developers to act as teams, so it includes every Agile project member in scoping and other team decisions. It is not necessarily useful for writers to participate in those decisions.

When figuring out how to fit into Agile, doc teams should keep the goals of Agile in mind. See your company's Agile evangelist for details for your company, but my initial list of goals would be to empower employees, create super-functional teams, reduce useless bureaucracy, create user-focused output, and respond quickly to market needs. Doc managers should go to the team that organizes Agile in their company and provide that team with some rough requirements for integrating writers into Agile. After that, it's a matter of working with the Agile team to finalize a list of goals, requirements and rules for writers. (There might be different sets for different levels of writer.) Every context has its own needs, but here are some sample doc goals, requirements and implementation rules. (Note that this is not intended to be a complete or cohesive set; plus, ideally the goals, requirements and rules should align.) Sample goals:

• Writers should have more and better communication with developers.
  
• Writers should have a thorough understanding of users, the market and the product.

Sample requirements:

• If there are no product specs, the writer needs comprehensive use case scenarios, a working sample to test, etc.
  
• The doc manager will not be on the Agile teams, but needs to evaluate and prioritize resources.
  
• Writers should sit with the developers on their Agile project.
  
• Writers should review terminology and usability issues early in the design phase.
  
• During the project, writers should review resource strings (error messages, UI text, etc).
  
• Writers {need to | should not} participate in multiple Agile projects at the same time.

Sample Agile implementation:

• If a senior writer is on an Agile team, the writer should assist the Product Owner with the creation of user stories.
  
• Writers should attend only review meetings until they start writing.
  
• Writers should start writing when the feature is complete, stable, and has been tested.
  
• Writers should write throughout the process, documenting every iteration.
  
• Writers should work one iteration behind the rest of the Agile team.
  
• The writer should be considered a Stakeholder for the project.

Re the requirement that writers will begin documentation only when a feature is complete and tested, Development may want iterations of the product to be documented for internal testing or other reasons, which is fine - but may require more writers. In addition, if a company wants to continuously deliver software updates with docs - and do it at a lightning fast pace - they might have to realize that doc productivity will fall and they'll need more writers.

I think the reason that doc teams aren't proactive enough in stating their requirements is the way that Agile is often introduced. There is a lot of emphasis on denouncing other processes, assimilating employees, and broaching no dissension. (This is a lot like the way DITA typically gets introduced.)

Agile evangelists (like DITA evangelists) frequently feel that the most important issue is employee attitude, and they are overly sensitive to anything that might be considered negative. But docs simply aren't an easy fit for Agile, and it's important to figure out where the problems are before devising a solution. All too often, writers are just made members of Agile teams and left to muddle through - which usually doesn't work very well.

When design and docs fail

Two Elections Canada workers were fired this week because they didn't understand the difference between encryption and compression. They were told to secure a USB flash drive that held information about voters. Instead of encrypting the data they compressed it, thinking compression was the security feature. Then the drives were stolen. (link)

I have documented encryption and compression, not for end users but for developers. When I read the article I had an immediate understanding (or at least guess) of why the Elections Canada workers were confused. The failure might have progressed something like this:

1. The internal process of encrypting and compressing data is similar (even though the end use is very different) so when the API was designed, encryption and compression were combined. For example, an API that I once documented used the encode method to both encrypt and compress data. Developers chose encryption and/or compression by setting parameters in the method.
   
2. The tech writer followed the API design and documented encryption and compression together. Yes, that's what I did. Even as I did it I realized it was wrong, and I think that's why it stuck in my head. Worse, I went on and on about all the fancy encryption options but threw in compression as a side note. (There just wasn't that much to say about compression: it was essentially a trivial add-on.).
   
3. The app developer followed the API design and the API documentation, and again implemented them in one feature in the UI, calling them Encryption and Compression.
   
4. The tech writer for the app followed the design of the UI.
   
5. The end user was faced with a USB drive that they knew had a security feature, and the UI had two side by side features, Encrypt and Compress. They guessed and chose the wrong one.

I checked out some secure USB drives, and I can see why users would be confused. The terms might be explained in the end user booklet, but if it's not clear in the UI then they probably didn't see it. Or perhaps they saw it but their eyes glazed over because of the lengthy descriptions of encryption algorithms. It would be much better for the app UI and end user docs to separate the two features and call them "Password protect your data" and "Compress data to free up file space." Important features should be completely clear in the UI, without having to resort to the docs. Way back in the API design, security features should have been separated from compression features. At the least, the developer docs should have handled them separately.