tag:blogger.com,1999:blog-86972507392213551022024-02-07T14:58:38.949-08:00WTFM*Write the Fabulous ManualAnonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.comBlogger22125tag:blogger.com,1999:blog-8697250739221355102.post-88839281831036086332012-04-12T17:28:00.000-07:002012-04-12T17:28:51.455-07:00Top 10 reasons why soft skills matter for writersI recently participated in a discussion about a blog post on <a href="http://www.contentrules.com/blog/how-to-find-good-programmer-writers/">How to Find Good Programmer Writers</a>. 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.)<br />
<br />
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.<br />
<br />
<ol>
<li>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.</li>
<li>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.</li>
<li>Writers need to be constantly learning new things. Without curiosity, they have no motivation to stay fresh in their technical skills.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>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.</li>
<li>In general, it's just more pleasant to work with nice people.</li>
</ol>
<div>
What other situations occur to you that require soft skills for writers? What soft skills are particularly important?</div>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-51574838160312192422012-04-06T14:59:00.001-07:002012-04-06T15:02:43.439-07:00Where'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:<br />
<h3>
<br /></h3>
<h3>
Forums</h3>
<div class="p1">
<a href="http://stackoverflow.com/">Stack Overflow</a><br />
<br /></div>
<h3>
Code Repositories</h3>
<div class="p1">
<a href="http://code.google.com/">Project Hosting</a></div>
<div class="p1">
<a href="https://github.com/">GitHub</a><br />
<br /></div>
<h3>
</h3>
<h3>
Coding Tutorials</h3>
<div class="p1" style="font-size: medium; font-weight: normal;">
<a href="http://www.codecademy.com/">Codeacademy</a><br />
<br /></div>
<h3>
Recorded Video</h3>
<div class="p1">
<a href="http://www.youtube.com/">YouTube</a></div>
<div class="p1">
<a href="http://vimeo.com/">Vimeo</a><br />
<br /></div>
<h3>
Live Event Announcements</h3>
<div class="p1">
<a href="http://www.meetup.com/">Meetup</a></div>
<div class="p1">
<a href="http://lanyrd.com/">Lanyrd</a><br />
<br /></div>
<h3>
Presentations and Slidedecks</h3>
<div class="p1">
<a href="http://www.slideshare.net/">Slideshare</a></div>
<div class="p1">
<a href="http://speakerdeck.com/">Speaker Deck</a><br />
<br /></div>
<div class="p1">
Any good collaborative developer site should include the highest quality relevant content from these sites.</div>
<div class="p1">
<br /></div>
<div class="p1">
What am I missing? What other great developer resources do you know about?</div>
<br />Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-88342106817928758612012-03-30T13:53:00.002-07:002012-03-30T13:53:42.325-07:00Changing the game<div class="separator" style="clear: both; text-align: center;">
<a href="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhrbLGlEEYr2v651EOGsHzDydAj7q5DSVFRGMcUqnt1U8p6Fe4n58ZaChD74UWFUstlnUY4MQf9hzko2Sqt0dSEcLV8asyr9ORLDTdfU-Sz4u9IGo1EYvuM9-FDxdwWxTrFoSmek_WE1ws/s1600/Moneyball_Poster.jpg" imageanchor="1" style="clear: right; float: right; margin-bottom: 1em; margin-left: 1em;"><img border="0" height="320" src="https://blogger.googleusercontent.com/img/b/R29vZ2xl/AVvXsEhrbLGlEEYr2v651EOGsHzDydAj7q5DSVFRGMcUqnt1U8p6Fe4n58ZaChD74UWFUstlnUY4MQf9hzko2Sqt0dSEcLV8asyr9ORLDTdfU-Sz4u9IGo1EYvuM9-FDxdwWxTrFoSmek_WE1ws/s320/Moneyball_Poster.jpg" width="215" /></a></div>
Inspired by a recent blog post, <a href="http://onstartups.com/tabid/3339/bid/76799/Startup-Lessons-From-17-Hard-Hitting-Quotes-In-Moneyball.aspx">Startup Lessons from 17 Hard-Hitting Quotes in "Moneyball"</a>, I just watched the movie for the first time.<br />
<br />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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
There were a couple of speeches in Moneyball that really hit home for me, in this context.<br />
<br />
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."<br />
<br />
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.<br />
<br />
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."<br />
<br />
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.<br />
<br />
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?<br />
<br />Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com2tag:blogger.com,1999:blog-8697250739221355102.post-55790464779991866482012-03-27T19:57:00.000-07:002012-03-27T19:57:08.614-07:00How to build a website in ten easy stepsI recently stumbled through the process of creating <a href="http://www.engageyourdevelopers.com/">a website for my new company</a>. I thought I'd consolidate my learnings into a blog post in case they're helpful to any of you. <br />
<br />
<ol>
<li><b>Write down what you want to say. </b>Before you start designing anything, sit down with a <a href="https://docs.google.com/">Google doc</a> 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.</li>
<li><b>Organize what you've written down into a logical collection of web pages. </b>Sort out what you want to say into a set of pages that makes sense. </li>
<li><b>Purchase a template that basically gives you the architecture your content requires. </b>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.<br />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.<br />I did a lot of searching before I stumbled across <a href="http://themeforest.net/category/all">ThemeForest</a>, which is ultimately where I found the design for my site. The templates they offer are well designed and competitively priced.</li>
<li><b>Add your content to the template; adding, subtracting, and moving things around as needed. </b></li>
<li><b>Customize the site design using custom graphics and fonts. </b>This is not actually as difficult or expensive as it might sound. <a href="http://www.istockphoto.com/">iStock Photo</a> is a great resource for graphic art. <a href="http://www.google.com/webfonts">Google WebFonts</a> 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.)</li>
<li><b>Set up tracking so you can evaluate and optimize traffic to your site. </b>Generate <a href="https://www.google.com/webmasters/tools/home?hl=en">Google Webmaster Tools</a> and <a href="http://www.google.com/analytics/">Google Analytics</a> tracking codes and include them on your pages, as explained on the linked sites.</li>
<li><b>Think of, and reserve, a reasonable domain name. </b>Good luck. Finding a good domain name that hasn't already been reserved is next to impossible.</li>
<li><b>Find a web hosting provider and upload your site. </b>I chose <a href="http://www.bluehost.com/">Bluehost</a> and have been happy with them. Their customer service was helpful when I was having an FTP problem.</li>
<li><b>Set up domain-specific email and calendar accounts. </b>A domain-specific account is much more professional than a generic web account. <a href="http://www.google.com/apps/intl/en/business/smbs.html">Google Apps</a> gives you the convenience of Gmail and Google Calendar for domain-specific accounts. </li>
<li><b>Drive traffic to your site. </b>Use <a href="http://en.wikipedia.org/wiki/Search_engine_optimization">Search Engine Optimization</a> best practices to drive organic traffic to your site, and <a href="https://adwords.google.com/">paid advertisements</a> to include your site in targeted ads.</li>
</ol>
<div>
Here's what I ended up with: <a href="http://www.engageyourdevelopers.com/">DevComm: Engage Your Developers</a>. Comments and feedback welcome!</div>
<div>
<br /></div>
<div>
What other great website development resources do you know of?</div>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-65982957404842507312012-03-24T12:00:00.000-07:002012-03-24T12:00:00.586-07:00Corporate Identity 101A corporate identity has a few basic required components:<br />
<br />
<ul>
<li><b>Company name</b><br />Don Dodge recently gave a good interview on <a href="http://news.cnet.com/8301-19882_3-57393460-250/startup-secret-44-a-rose-by-any-other-name/">choosing a company name</a>. 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.</li>
<li><b>Logo</b><br />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 href="http://thisisrusa.com/identity/">a custom logo</a> for me.</li>
<li><b>Business card</b><br />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 <a href="http://www.qrstuff.com/">QRStuff</a>. If you want to go the simple route, you can get a standard business card design from many printers.</li>
<li><b>Website</b><br />This one's complex enough to merit its own post, which is coming soon.</li>
</ul>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-55547175925643863892012-03-17T10:00:00.000-07:002012-03-17T10:00:02.440-07:00Resources for starting a new companyAs 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:<br />
<ul>
<li>Should I structure my company as a consulting company, or a product company? Or both?</li>
<li>Is it just me, or do I involve others? If I involve others, in what capacity?</li>
<li>What kind of business do I set up: Sole proprietorship? LLC? S-Corp? C-Corp? Anything in between? When do I file the paperwork?</li>
<li>What legal considerations do I need to be aware of?</li>
<li>Do I need funding? If so, what for?</li>
<li>Should I fund this myself (what's known as "bootstrapping", I've come to find out) or seek venture capital?</li>
<li>What's the difference between angel investors and and venture capitalists, and why would I seek out one over the other?</li>
<li>How do I find a designer to help me set up a marketing presence, like a logo, website, business cards, etc?</li>
</ul>
<div>
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.</div>
<div>
<br /></div>
<div>
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:</div>
<div>
<ul>
<li><a href="http://ycombinator.com/">YCombinator</a>: A micro-financing / mentoring organization that helps a select group of startups develop a business model and seek funding.</li>
<li><a href="http://www.score.org/">SCORE</a>: 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.</li>
<li><a href="http://www.svforum.org/index.cfm">SVForum</a>: 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.</li>
<li><a href="http://fi.co/">The Founder Institute</a>: 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.</li>
</ul>
<div>
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?</div>
</div>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-87501758749234362972012-03-12T13:35:00.005-07:002012-03-12T13:35:53.456-07:00Being deliberate about career choicesHello! Long time no talk. <br />
<br />
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.<br />
<br />
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. <br />
<br />
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.<br />
<br />
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.<br />
<br />
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?" <br />
<br />
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. <br />
<br />
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.Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-76113635262686716752012-02-03T10:53:00.000-08:002012-02-03T10:53:20.470-08:00The next chapter of my careerWell, folks, the time has come for me to move on. Today is my last day at Google. <br />
<br />
After I <a href="http://jenjobart.blogspot.com/2011/12/why-i-eliminated-my-own-position.html">eliminated my position</a>, 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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
So. What's next for me? <br />
<br />
I'm going to start my own company, helping organizations implement collaborative developer documentation.<br />
<br />
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.<br />
<br />
"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.<br />
<br />
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. <br />
<br />
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.<br />
<br />
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.<br />
<br />
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. <br />
<br />
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.<br />
<br />
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.<br />
<br />
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?Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com4tag:blogger.com,1999:blog-8697250739221355102.post-82626153029520764132012-01-13T12:00:00.000-08:002012-01-13T12:00:04.086-08:00The future of technical communicationFor 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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
Two examples of sites that do a good job of this are:<br />
<ul><li><a href="http://www.instructables.com/">Instructables</a></li>
<li><a href="http://www.ifixit.com/">iFixit</a> </li>
</ul>Both sites seamlessly merge different, related content sources, including docs, forum answers, photos, and video.<br />
<br />
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 href="http://www.ifixit.com/User/Graph/224642/Richdave">a particularly good algorithm</a> for establishing and showcasing contributors' reputations.<br />
<br />
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 <a href="http://www.instructables.com/id/How-to-Write-an-Instructable-1/">how to write good content</a> (although it would be nice if this page were easier to find.)<br />
<br />
What are other important considerations for collaborative sites? What are examples of your favorite sites?Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com2tag:blogger.com,1999:blog-8697250739221355102.post-41851238388639903622011-12-24T15:55:00.000-08:002011-12-24T15:55:54.728-08:00The Potential of ForumsI've spent the last couple of weeks recovering from a tonsillectomy. Having your tonsils taken out when you're pushing 40 sounds (and is) insane. Surprisingly, though, there are a fair number of people who do it. When I stumbled across a forum of people my age undergoing the same surgery at the same time, I was happily surprised.<br />
<br />
The official documentation that my hospital and doctor provided was helpful. It told me what kind of surgery I'd be having done, the expected prognosis and recovery time, and detailed the medications I could take. However, as with any documentation, it was missing a lot. What the official docs were missing, the forum provided. Forums are the perfect complement to documentation. <br />
<br />
<span style="font-size: large;">2 things that forums are great at</span><br />
<br />
In general, forums are great for two things. First, they're a good medium for people in similar situations to share practical advice with one another. I'm thankful to the person who discovered that chewing Dentyne Ice gum helps with ear pain after surgery, and am very glad that person thought to share his discovery. That kind of information would never have been included in my doctor's documentation, but it's nonetheless very helpful.<br />
<br />
Forums also provide emotional support. Just knowing that someone else is grappling with the same thing; whether that be going through a medical procedure, or trying to write code against the same libraries, is heartening. Your peers for whatever's at hand are uniquely able to appreciate your triumphs and empathize with the problems you're facing.<br />
<br />
<span style="font-size: large;">2 things that would make forums even better</span><br />
<br />
Forums would be even better if the information that goes into them were easier to get out. They work well for people who are facing the same problem at the same time and can have a real-time conversation about it. But once that conversation is archived, it's harder for Joe Schmoe to come along a few weeks later and get all the learnings that the first people figured out together. The same learning process is often just repeated over and over with new people. Search should be improved for forums so that people can learn from past conversations, as well as current conversations. Even better would be the addition of artificial intelligence to forums, so that forum conversation about documented topics could automatically be added to the relevant documentation. That would bring the best worlds of documentation and forums together; a perfect marriage.<br />
<br />
The second thing that would make forums better would be a way for participants to create a reputation based on their contributions, at their discretion. This reputation should be persistent across forums of similar nature; for example, a developer's Java reputation and her Android reputation should combine to show her skills as an Android app developer. <a href="http://stackoverflow.com/badges">Stack Overflow</a> has a good algorithm for reputations; it would be great if we could extend that to other sites. <br />
<br />
How do you use forums? What works about them, and how could they be better?Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com3tag:blogger.com,1999:blog-8697250739221355102.post-3590934970499928182011-12-09T11:30:00.000-08:002011-12-12T10:26:30.141-08:00Why I eliminated my own positionA couple of months ago, I directly managed all of Google’s developer documentation tech writers. Through their efforts, I was responsible for the documentation for all of Google's developer products and APIs. It was a wild ride and a hell of a fun job.<br />
<br />
As of today, I have intentionally eliminated my own position by successfully merging all of those writers into the Developer Relations teams for their product. Want to hear the story of how and why I did this?<br />
<br />
A couple of years ago, I decided to try my hand at management. I liked the idea of helping people grow their careers, and I like thinking outside the box about how to match up my group's goals with the company's business objectives. Management seemed like a natural fit.<br />
<br />
Shortly after I accepted the job, I started to perceive ways I could help the team have a bigger impact. I refocused my team’s efforts on a portfolio of high-priority projects, optimized team performance, led the team through a cultural shift, and built strategic relationships with other teams around Google. <br />
<br />
After about a year, my efforts started paying off. We had become a measurably stronger group, with an unmatchable skillset and a very strategic portfolio. The relationships I had been working on came to fruition. My group formally moved from being part of a central documentation group at Google, to being organizationally aligned with Developer Relations. <br />
<br />
That was a great first step. It made our mission clear, and it gave us a framework for success. It meant that we were directly interfacing with our developers, so our work was driven by our developer needs, as should be the case.<br />
<br />
When we moved into Developer Relations, all of the writers reported to me as their people manager, and worked closely with the product leads for project guidance. Over the course of the next year, I perceived the writers becoming more and more entrenched in their project team. My role became less and less critical as time went on. It became apparent that it would be better for everyone: Google, our developers, Developer Relations, my writers, and myself, to roll the writers directly into their teams. <br />
<br />
That's what we officially did a couple of weeks ago, and so far, it's going great! The writers are the first people to see new features, so they're the "canaries" as it were, and can help everyone else on the team figure out how new features and APIs work. The Developer Programs Engineers and Developer Advocates talk to our developers every day. When they identify things that are tripping up developers, they can pass that info back to the writers, so that the writers can make sure these things are clearly explained in the docs. <br />
<br />
Companies vary wildly in how they define the reporting structure for their technical writing teams. Sometimes tech writers report up through product development, sometimes through sales, sometimes through customer relations. My team has found our greatest success so far reporting up through the Developer Relations teams for the products we document. With this alignment, we’re able to put ourselves in our developers’ shoes, write documentation that developers actually read, and advocate for product decisions that will be most beneficial to our developers. <br />
<br />
How is your team structured? What works about that structure, and what doesn’t?<br />
<br />
PS: You might ask - where does this leave me? I had a lot of fun over the last couple of years, and am looking forward to finding out what comes next!Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com4tag:blogger.com,1999:blog-8697250739221355102.post-75343630922402167592011-11-23T12:44:00.000-08:002011-11-23T12:44:20.748-08:00LavaconA good conference should get you out of your day-to-day tactical problems, and get you focused on the big picture. It should put you cheek-to-cheek with people who are excited about being in the same space, and who are interested in exploring beyond the status quo. You should return to your day job with a renewed sense of energy, and a plethora of ideas that will inspire you to do better, achieve more, think bigger. <br />
<br />
For tech writers, that conference is <a href="http://lavacon.org/">Lavacon</a>. It's dedicated to content strategy, which, in my mind, means thinking outside the box about why and how we produce content. Social media, new content types (such as mobile) and an increasingly global environment mean that the communication approaches we've used in the past are no longer good enough. The role of a tech writer is changing; there's simply too much content to have only one role dedicated to writing all of the docs needed.<br />
<br />
My favorite session was <a href="http://lavacon.org/sessions/help-2-0-welcome-to-the-new-world">Scott Abel's "Help 2.0" presentation</a>. His ideas about how to leverage the crowd to create and organize content were revolutionary. I think that crowd-sourcing has great potential for developer docs and have been thinking about how to do it ever since.Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com1tag:blogger.com,1999:blog-8697250739221355102.post-11521819388514940732011-11-11T10:27:00.000-08:002011-11-11T10:27:04.246-08:00Telecommuting for tech writers: feasible or not?Does it make sense to hire a tech writer who is not co-located with the team? The answer is: it depends. Here are questions to ask to help you decide.<br />
<ul><li><b>How many people does the tech writer need to interface with?</b><br />
The more people involved with a project, the more valuable it is for the tech writer to be onsite so s/he can gain economy of scale by meeting with multiple people at once.</li>
<li><b>How formalized is the exchange of information in the company?</b><br />
If a company has, and follows, fairly stable specifications and project plans, it's easier for the tech writer to work at a distance. If critical information tends to be communicated in hallway conversations and over lunch, it's better for the tech writer to be onsite so s/he can take part in these conversations.</li>
<li><b>How important is it that the "powers that be" at the company recognize the value of tech writing?</b>As a general rule, face to face contact increases perceived value. If education about the value of tech writing is strategically important in the long term, it's better for the tech writer to be located onsite. If it's okay that tech writing be viewed as a commodity, then telecommuting is fine.<b><br />
</b></li>
<li><b>How specialized are the requirements of the position? </b><br />
As with any profession, the best tech writers are hard to find. The more specialized the skillset of the writer you are recruiting, the more you may have to gain by agreeing to let the tech writer telecommute.<br />
Many of the most technical API writers are qualified to be software developers. They have consciously chosen to earn less income as tech writers in order to make gains in work/life balance, and telecommuting is one of the top benefits they are seeking. You can attract exceptional talent by allowing telecommuting.</li>
</ul>What other factors are important to consider with respect to telecommuting? Are there additional advantages or disadvantages I've neglected to mention?Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com3tag:blogger.com,1999:blog-8697250739221355102.post-46606077521631674662011-10-28T16:22:00.000-07:002011-10-28T16:22:21.474-07:00Evaluating Tech Writer PerformanceIt's that time of the year again: performance review time. As I sit here making my way through the stack of reviews in front of me, I'm reflecting on the process.<br />
<br />
I actually like perf reviews. I have a very strong team. Perf reviews give me the opportunity to reward the ones who really nailed it this year, and to give others the feedback they need to be one of the writers I'm rewarding at this time next year.<br />
<br />
Also, perf reviews give me a chance to celebrate all the great work my team has done over the past year. Tech writers are invariably on the forefront of the most exciting new technology, and needless to say, there's a lot of fun stuff going on at Google.<br />
<br />
Essentially when I'm evaluating tech writer performance, I look at three things:<br />
<ul><li>What did the person write?</li>
<li>How good was it?</li>
<li>How hard was it to write?</li>
</ul><div><b>What did the person write?</b></div><div>My team comprises about 25 writers, give or take. That's an extremely lean team when you consider everything we write: <a href="http://developer.android.com/">http://developer.android.com/</a>, <a href="http://code.google.com/">http://code.google.com/</a>, <a href="http://developers.google.com/">http://developers.google.com/</a>, <a href="http://www.chromium.org/">http://www.chromium.org/</a>, and more. In any given year, most of my writers write the equivalent of at least a couple of books. They stay busy! </div><div><br />
</div><div><b>How good was it?</b></div><div>I read what my team writes, and look for clarity, completeness, and quality. I also look at stats, such as Analytics data, bug queue metrics, and forum data, that objectively tell me how effective the docs were.</div><div><br />
</div><div><b>How hard was it to write?</b></div><div>This is the tricky one with tech writing. You often have to dig to find out what's behind a document. It might take a day or a month to write the same one-page developer guide; there's really no way of telling on the surface. It depends on what source information there is to start with, including specs, other docs, or sample code, how complete the API is, how well-designed the API is, and how helpful the related subject matter experts are. The only way to find this out is to keep in close communication with the writer, and to solicit feedback from the team the writer works with. </div><div><br />
</div><div>My team has several different levels of tech writers; some straight out of college, some with a long career history under their belt, and many in between. In general, the more senior the tech writer, the more self-sufficient they should be, and the better they should be able to find creative, strategic solutions and guide the work of others.</div><br />
How do you think tech writers should be evaluated? If you work with another role, what differences or similarities are there in how performance is evaluated for that role?Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com1tag:blogger.com,1999:blog-8697250739221355102.post-96412129496361082011-10-20T22:05:00.000-07:002011-10-20T22:05:58.321-07:00Top 10 Components of an API DocIn order of importance: <br />
<ol><li>Sample code</li>
<li>Complete reference, including expected behavior, argument ranges, default values, possible side effects, and related methods</li>
<li>Error handling information</li>
<li>Developer's guide</li>
<li>Changelog or release notes </li>
<li>Installation and configuration information<br />
</li>
<li>Tutorial or codelab</li>
<li>Conceptual overview</li>
<li>FAQ </li>
<li>Usage info for related developer tools </li>
</ol>What do you think, folks? What'd I miss? What do you think is out of order?Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com4tag:blogger.com,1999:blog-8697250739221355102.post-42471802353908880132011-10-14T18:32:00.000-07:002011-10-14T18:32:14.653-07:00Focusing Your Portfolio<div style="font-family: inherit;"><span class="Apple-style-span" style="border-collapse: separate; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;"></span></div><div style="background-color: transparent; font-family: inherit;"><span id="internal-source-marker_0.9478279727045447" style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Lately, Google's been announcing decisions it's made to <a href="http://googleblog.blogspot.com/2011/10/fall-sweep.html">focus efforts on key products</a>. I've made similar decisions to focus the efforts of my team, and thought it would be interesting to talk about why and how I did this.</span><br />
<span id="internal-source-marker_0.9478279727045447" style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;"> </span><br />
<span id="internal-source-marker_0.9478279727045447" style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">There are a few constant challenges in staffing tech writers:</span><br />
<ul><li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Product teams often don’t think of tech writers until the last minute.</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">It takes time to get to know a developer product well enough to document it, so it’s not usually possible to immediately refocus someone on a different project when requested to do so. Therefore, staffing takes time. </span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">The closer teams get to releasing a product without documentation, the more frantic they get, and correspondingly, the louder they get.</span></li>
</ul><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Unfortunately, the squeaky wheel gets a lot more attention than the smooth-running Lexus, so, if you don't have a prioritization framework, you sometimes get roped into making reactive staffing decisions that don’t make much sense in the long run. You may end up with a portfolio of projects whose only connection is that they are staffed by the most insistent product managers. This may result in your not being able to staff the most important, fastest-moving projects, and losing opportunities to do high-impact work.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">My team had fallen into this trap when I stepped up to management. Google has a myriad of interesting projects going on at any given time. As a company, it's known for its bottom-up management style. This is great for being empowered to get things done quickly and with a minimum of politics. However, it's historically been difficult to get a straight answer about what projects are most important.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">The writers on my team are extremely talented. They do great work on the projects we work on, and their project teams love working with them. However, previously, our portfolio consisted of a smattering of random projects that, taken as a whole, didn't make much sense. More importantly, we weren't solving many strategic business problems for Google. Because of that, we had a tendency to be overlooked when it came time for things like resources, recognition, and headcount allocations.</span><br />
<br />
<span style="font-size: small;"></span><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">The first thing I did to resolve this was to step back and make some deliberate decisions about what business problem we were trying to solve. In our case, that was "Support our developers." Then I made choices about what kinds of projects would do the most to help our developers. In some cases these choices led to our working on the documentation for key products. In other cases we had to think bigger; providing frameworks that let others contribute to the documentation with our guidance, or providing solutions for sticky problems that impacted multiple documentation sets at a time.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Since there wasn't really any clear external prioritization guidance, I had to come up with my own criteria. To do that, I made some high-level decisions about what factors might indicate that a project is important. The criteria I decided to use to evaluate project requests is as follows:</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">How many users does the product have?</span><br />
<ul><li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">If there is existing documentation, is it one of the X most-read doc sets at the organization based on <a href="http://www.google.com/analytics/">Analytics data</a></span><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">?</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">If the product is an API, how many requests are (or are projected to be) made to the API itself?</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">What’s the (projected) rate of adoption for the product?</span></li>
</ul><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">How strategic is the project?</span><br />
<ul><li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Is the project in the company high-level goals?</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Did it get a company or industry award?</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">How many engineers are on the project?</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">How many support people are on the project?</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">If the product is an API, does it enable developers to create applications that work with a strategic company product?</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Is the project focused on a high-level community goal that the company supports?</span></li>
</ul><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">How much revenue does the project generate?</span><br />
<ul><li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">How much money is the project projected to bring in this year?</span></li>
<li><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Will revenue increase or decrease over time?</span></li>
</ul><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Now, whenever I receive a documentation request, I ask the project lead to provide data about how the project measures up to these criteria. I use the data to make unbiased decisions about which projects to work on. I do this transparently, so that even if people don't always like the decisions I make, at least they understand why I make them.</span><br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;"> </span><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;"> </span><br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Vetting project requests is a good first step. The next step is to be proactive about seeking out strategic projects to work on. I do this by making sure I'm involved in key meetings; especially those where new projects are reviewed and discussed. This gives me information about what new projects are coming down the pike, in time to plan resources needed to staff them. At the same time, it gives me the opportunity to meet the project stakeholders and raise awareness of the value of documentation and the work that my team does. </span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">These days, developer product teams at Google are much more aware of the value of good documentation. The other day, in a product review meeting, a product manager said "We can have all the great APIs we want, but without good documentation, we have nothing." (By the way, he's right. :-) ) People think of us when they're planning new projects, and get us involved early.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Focusing our portfolio was not an instant process, to be sure, but it was worth it. It drastically increased the impact my team's work has on our developers. Once Google understood the role that tech writers play in supporting our developers, our group gained the status, recognition, and respect that our work merits. </span></div>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com2tag:blogger.com,1999:blog-8697250739221355102.post-82057355607137729962011-10-05T12:57:00.000-07:002011-10-05T15:19:17.284-07:00How to Hire a Great API WriterThe other day, a friend asked my advice about interview questions for tech writing candidates. He needed to hire some writers to document some APIs for his company. Since he isn't a tech writer himself, he wasn't sure what to ask.<br />
<br />
The reality is that usually someone other than a tech writer is the hiring manager. So I thought I'd share my thoughts on how to hire great writers, especially those who write developer documentation. <br />
<br />
<b>Screening Resumes</b> When you screen resumes, look for someone who has experience explaining highly technical information. If you're hiring a junior writer with little to no documentation experience, look for related roles. For example, maybe they provided tech support for their school computer lab. Or if they're switching careers, maybe they provided customer support for developers, or worked in an environment testing APIs. Pro-bono experience writing similar documentation for an open source project is great; it shows proficiency with similar projects, and also shows initiative.<br />
<br />
I tend to approach ex-engineers with caution. Some of them make fantastic tech writers, but it's important to dig deeper into their motivation for a career change. Look for those who have discovered that they enjoy writing specs and communicating with customers more than they enjoy debugging code, so they've decided to make a career out of writing. Shy away from people who would prefer an engineering job but, for some reason, can't get hired as an engineer. At best, they will transfer to a new job at their first opportunity. At worst, they will hate their job and damage team morale.<br />
<br />
In the education section of the resume, look for evidence of continuing education in related topics; for example: technical writing, programming, or project management classes. A successful technical writer needs to be constantly learning, since the work we're doing is always on the cutting edge of technology, and also because our jobs are so varied and require many skills from many different curricula.<br />
<br />
As long as the candidate has a bachelor's degree, don't worry too much about what field it's in. There are very few technical writing degree programs in the US, and there are as many paths into tech writing as there are tech writers. I've met successful tech writers who have degrees in journalism, business, computer science, teaching, and philosophy, among others.<br />
<br />
<b>Evaluating Work Samples</b> Any tech writer worth his salt will have a portfolio of sample work. Even someone just getting into the industry should have something to show you: a spec he wrote, an exercise from a class he took, or documentation he wrote for an open source project.<br />
<br />
When you request samples, be sure to ask questions to ascertain how much of it the candidate wrote himself. Did he write it from scratch, revise an existing document, or co-write it? Did he have support from an editor to help with the writing, or a support from a publisher to help with publishing logistics? You're really looking for work that the candidate did himself, so ask him for samples he wrote himself. If he doesn't have any of those available, first ask yourself why not, and then at least get a clear picture of how much involvement the candidate had in writing the samples he does have.<br />
<br />
When you review samples, evaluate whether the candidate is explaining things clearly. If you don't have any relevant domain knowledge, it's possible that you won't understand everything; however, at least part of it should resonate. Also, look for typos, misspellings, grammatical errors, and other things that indicate potential laziness. Tech writers' work isn't always perfect, but writing samples should be as close to perfect as possible.<br />
<br />
<b>Conducting the Interview</b> During the interview, try to ascertain that the candidate:<br />
<ul><li>knows what goes into good technical documentation</li>
<li>has the technical aptitude to pick up the particulars of your project</li>
<li>shows the initiative needed to create great documentation without minimal impact on the productivity of others in your company</li>
</ul>To that end, here are some basic interview questions to ask, as well as advice on what kinds of answers to look for.<br />
<br />
<b>Q: What kind of information should be included in an API reference?</b><br />
A: In addition to the basics (explanation of what the method does, arguments, and return values) a good writer should mention one or more of the following: acceptable ranges of values for arguments, default values, what happens if the method gets called using the default values, possible side effects of calling the method, a list of related methods that are often called with the one in question. Developers read the documentation to find out information they can't get by simply looking at the header file, and they'll be frustrated if that information isn't included.<br />
<br />
<b>Q: What kinds of documents need to be written to document an API?</b><br />
A: At minimum, you'll need a reference, a basic developer's guide that explains how you put the methods together, and a basic sample application. If possible, the reference should be automatically generated using javadoc, doxygen, or similar technology. If possible, the sample application should be compilable, so someone can just use it as the starting point for their own application. If time allows, developer documentation should also include as many of the following additional components as possible: A tutorial that walks through a complex sample app, one concept at a time, release notes that explain what changed between releases, so developers know what they have to do to update their application to the latest version, and in-depth documentation that explains any of the concepts that the API relies on; especially if the developer isn't likely to be familiar with those concepts.<br />
<br />
<b>Q: Explain the technology involved </b><b>with one of the samples you sent.</b><br />
A: Even you aren't the target audience for the sample, the candidate should be able to explain it in a way that you understand it. A key skill for a tech writer is being able to explain things clearly. If you don't understand it after the candidate's explanation, it's not you--it's the candidate. Move on.<br />
<br />
<b>Q: Now assume you're talking to your grandmother. Explain the technology to her.</b><br />
A: A good tech writer can explain even the most complex of concepts simply to a non-technical audience. I once had a candidate explain the concept of inheritance by saying that his DVD player, stereo and TiVo have an inheritance relationship, because they are all different manifestations of the same kind of technology.<br />
<br />
<b>Q: Explain the process you went through to write one of the samples you sent.</b><br />
A: You're looking for evidence of self-sufficiency. The candidate should do all the research and reading she can (within reason) to avoid wasting engineers' time with basic questions. The candidate should not rely on a spec, or any other document where someone else is writing the majority of the documentation. With enough research, and asking the right types of questions, a good tech writer should be self-sufficient enough to write documentation herself. Chances are you're looking for someone who functions as a one-woman show, so in an ideal situation, the candidate publishes documentation herself, rather than passing source docs off to a publishing team or webmaster. If the writer used an editor, find out what kind of edits were recommended. If a developmental (structural) edit was required, then that demonstrates a fundamental inability to organize information logically, and you should walk away. Look for the ability to take and incorporate feedback. Ask how the candidate requests information and feedback from engineers, and look for evidence of the writer taking responsibility for the content, rather than pushing that responsibility off to the reviewers.<br />
<br />
<b>Q: Explain what's happening in a simple snippet of code (that you provide)</b> This code should be written in one of the languages with which the candidate professes familiarity. It should contain a couple of basic constructs, like a loop, and an if, then directive. It should have an explicit return value and variables, and may also modify inherited variables. This is one of the few times where it's better to have less comments, so that you can ensure the candidate is really reading the code.<br />
A: The candidate should be able to basically explain what the code is doing. She should ask good questions about things that aren't obvious. Give the candidate time to think before answering.<br />
<br />
<b>What Not to Ask:</b> Don't ask a tech writer candidate questions about how to optimize code efficiency, questions about design patterns, questions about how to resolve bugs in code, or even puzzle/logic questions. Almost universally, none of the skills touched on by those questions are relevant to a tech writing job. There are very few tech writers who could answer these sorts of questions.<br />
<br />
<b>Checking references</b> Finally, it's important to check references. You'll probably get more information if you talk to someone who has left the company; today's HR laws dictate that any reference request made to a current employee will probably get passed directly to HR, who will be able to tell you little more than the dates that the candidate worked there.<br />
<br />
Ask open-ended questions, such as:<br />
<ul><li>What are <i>candidate's</i> strengths?</li>
<li>What are <i>candidate's</i> weak spots?</li>
<li>What's it like to work with <i>candidate</i> on a project? </li>
<li>If the reference worked with the candidate on a project he discussed during the interview, ask the reference for his perspective on how that project went.</li>
<li>Would you hire <i>candidate</i> again?</li>
</ul>Thus concludes my advice for hiring great technical writers. Good luck! Let us know how it goes.<br />
<br />
Oh, and if you're a tech writer looking for job-hunting advice, stay tuned for follow-up posts on how to get hired as a tech writer, and how to break into tech writing.Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com2tag:blogger.com,1999:blog-8697250739221355102.post-2250685625355082552011-09-26T15:07:00.000-07:002011-09-26T15:07:59.094-07:00Soliciting Useful Community Collaboration (or, how to get good community content that isn't interspersed with Viagra ads)Community collaboration is key, for the reasons I've mentioned in previous posts. But getting good collaboration isn't straightforward. You have to architect the site correctly, accommodating the reality of different collaboration types. You also have to guide the dynamics of a community in order to expose the useful feedback and prevent the entire site from being overrun by trolls, bad information, and Viagra commercials.<br />
<br />
There are a couple of different models for encouraging community feedback.<br />
<br />
<b><span style="font-size: large;">Letting people add notes to the doc</span></b><br />
<br />
One model is to maintain a canonical, source controlled doc, but let people add notes to the end of each doc page. <a href="http://www.php.net/manual/en/language.basic-syntax.phpmode.php">php.net </a>is an example of this model can work. As illustrated by the page I linked to, what makes this work is that contributors post useful information at the end of each page. The community-contributed content adds to what is already in the documentation, and is helpful to the wider community.<br />
<br />
One advantage of this model is that it opens the docs up to collaboration, while ensuring the quality and reliability of the canonical docs. This offers protection against trolls, and also against people who have good intentions, but are just wrong. <br />
<br />
The disadvantage of this model is that it usually garners a different type of feedback than you'd want. Users generally treat the comments section at the end of a page as either a forum, or as a place to give feedback about the docs. At best, community feedback generally consists of something like, "I'm trying to do X, please help" or "This page states that this method returns A, but it actually returns B. Please fix the doc." At worst, the feedback areas end up being a dumping ground for spammy links to online pharmacies and porn sites.<br />
<br />
The way you get around this is to heavily moderate contributed comments, and address and remove those that aren't appropriate. Over time, the hope is that the docs will get enough appropriate comments that people will use those as an example, and begin to post the kind of thing you're looking for. Regardless, this will always require some moderation effort.<br />
<br />
In my opinion, your best bet with this model is to bypass it altogether. Instead, link to a dedicated forum where people can garner answers from the community, and link to an issue tracker where people can report issues with the docs. If that's what people want to do, it's better to just accept it and provide appropriate tools to help.<br />
<br />
<b><span style="font-size: large;">Letting people modify anything in the doc</span></b><br />
<br />
A second model is wiki, which opens up the docs entirely to community collaboration. The community can modify anything at all. <a href="https://developer.mozilla.org/en/Canvas_tutorial/Drawing_shapes">developer.mozilla.org</a> is an example of this model. You can access the collaboration history of each page by selecting "This page -> History" in the upper right hand corner. The <a href="https://developer.mozilla.org/index.php?title=en/Canvas_tutorial/Drawing_shapes&action=history">history for the page I linked</a> shows extensive community collaboration. <a href="http://en.wikipedia.org/wiki/Wiki">Wikipedia</a> is another well-known example of this model.<br />
<br />
Usually, contributors are required to sign in before they post. Contributions can be reviewed by a central moderator, or by the community, or both. <br />
<br />
Generally, as a contributor gains more credibility over time, their posts are subject to less oversight. Often what you end up with is a set of trusted core contributors, who are enthusiastic and familiar with the technology. You also have a long-tail of one-time or occasional contributors.<br />
<br />
I think this model is where the documentation industry is going, and it's generally a good model to adopt. There are a few things you need to do to make it successful, though.<br />
<br />
First and foremost, recognize the value of your top contributors. Give them some way to earn a public reputation on the site. Include them in events (either as attendees or speakers), send them t-shirts, give them early access to your APIs. As <a href="http://blog.pamelafox.org/2009/01/how-to-alienate-community-101-gurus.html">Pamela Fox mentioned in her post "How to Alienate a Community 101"</a>, though, you have to be careful that you do this in a way that recognizes the spectrum of contributions. Pamela's post contains good information about how to do that.<br />
<br />
Next, adopt a good model for moderating content. The most sustainable way to do this long-term is to let the community moderate. Have a voting system, and use votes to flag content that needs to be reviewed. Allow access level based on reputation, so those users who are most helpful in the forums have the most leeway to modify the docs. Even if you do these things, though, recognize that you'll still need to put some work into moderating content in the short term.<br />
<br />
<a href="http://www.mindtouch.com/">Mindtouch</a>, and <a href="http://www.atlassian.com/software/confluence/">Confluence</a> are a couple of out-of-the-box solutions for this model. I haven't worked with either one so can't comment on their effectiveness.<br />
<br />
<b><span style="font-size: large;">Encouraging, and linking to, discussion in a forum</span></b><br />
<br />
Embrace the fact that much of the useful hands-on discussion occurs in forums. There are several good sites for this, but one of the best sites I know of is <a href="http://stackoverflow.com/">Stack Overflow</a>. It is already in wide use, for good reason. It supports reputations and badges, which makes for a good contributor experience. It supports tags, which is useful for finding and linking to relevant content. <br />
<br />
If conversation about your product is happening in one of these forums, link to it. If not, encourage conversation there. Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-73806657896432007102011-09-23T17:37:00.000-07:002011-10-05T15:00:06.433-07:00Speaking to your audience<div style="font-family: inherit;">I've been having trouble getting started on this blog. There are a lot of things I'd like to talk about here... developer support, API usability, managing a team of writers, and, of course, documentation. The problem is that I haven't been able to figure out what to talk about first.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">It just struck me that the reason for dragging my feet is that I haven't thought about who my audience is.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">When you start a new tech writing project, the first thing you do is figure out your audience. Then you figure out what they're trying to do. Once you know your audience's starting point, and figure out where they're trying to go, you can figure out what you need to do to help them get there.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">The challenge with blogs, and with public web documentation in general, is that absolutely anyone can read what you're writing. If you're reading this right now, you could be a fellow tech writer (either just getting started in your career, or a veteran), a developer, or a tech writing manager. And those are just the basics. Heck, you could be a fly fisherman who stumbled across this page accidentally (and is probably wondering why he's still here.)</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">Web docs have similar challenges, especially those for APIs that are offered freely to the general public. One developer might be a student, who is trying to piece together an app over cold pizza at 3am because he saw an interesting article about the technology on Slashdot. Another developer might be writing an enterprise app as part of her day job. A third developer might be working on an cutting-edge application for that startup he always dreamed about creating. </div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">One developer might create web apps every day, and know everything that's out there about it. Someone else might be used to writing drivers in C, but have zero experience with Java. And yet another person might have no development experience whatsoever; they're trying to get something working by copy-and-pasting sample code and hoping for the best.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">How do you write one document that works for everyone?</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">Believe it or not, it is possible, depending on your definition of "write one document." You can't do it if you expect all of your readers to sit down and read a thousand-page manual from start to finish. But if you use good navigation and information architecture, and well-configured search, then anyone can find what they need.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">The navigation of your docs should work for as many of your typical developers as possible. People should be able to quickly find the docs that explain what they're trying to do, without having to read through a lot of irrelevant prose. As a writer, you should think about how to reuse information intelligently. For example, everyone will need to authenticate their app, so the docs that explain authentication should be linked from lots of places. On the other hand, only certain apps will need to use particular sequences of methods.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">The web is a goldmine of information. There's no need to explain the basics, such as how REST works. Find a good resource that explains it, and link to that resource.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">But most importantly, just take the time to think about who your audience is. Being cognizant of who is reading will help guide what you write, even if you just tuck that knowledge away in your subconscious and don't do anything about it.<br />
</div><div style="font-family: inherit;"></div><div style="font-family: inherit;">So back to this blog. If you're new to tech writing, or new to tech writing management, I hope this blog is helpful to you. Please feel free to email me with questions and topic requests. I'll link to additional helpful resources as I find them. If you're an old pro, or a developer, let's get a conversation going. Please jump in and argue my points, if you're so inclined! Regardless of who you are, you can navigate the blog by topic or by search. </div>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-54073076210268815552011-09-23T13:20:00.000-07:002011-09-27T11:30:32.157-07:00Lots of heads are always better than one<div style="font-family: inherit;">With the advent of web-based docs, users completely gave up the notion of reading an entire 1000-page docset from start to finish. Here's how it works now:</div><ul style="font-family: inherit;"><li>People only read documentation under duress. If people want light reading, they'll pick up the comics section of the local paper. If people want to learn how to use an API, they'll find some sample code (probably on a forum somewhere) and try to make it work for their own app. They won't touch the official docs until they get stuck, and can't easily find the answer to their problem elsewhere.</li>
<li>The next thing they'll do is search the official docs for the answer and/or scan the nav bar for something that might help. If they find something that seems to be relevant, great! If not, you've already lost them.</li>
<li>If the section they navigate to has the answer to their problem, they might be inclined to keep reading. If not, you've lost them.</li>
<li>If they consistently find useful information in the docs, they'll start to trust the docs and will keep coming back to them. But, as one of my favorite candidates, Doug Anderson, said to me in an interview, "You only get so many opportunities with documentation before you teach people not to look at it."</li>
</ul><div style="font-family: inherit;"><span class="Apple-style-span" style="color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;">And that's why it's so hard for a single tech writer to create engaging, satisfying documentation. There are too many ways it can go wrong.</span></div><div style="font-family: inherit;"><span class="Apple-style-span" style="color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;"><br />
</span></div><div style="font-family: inherit;"><span class="Apple-style-span" style="color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;">That's also why the traditional definition of one writer being solely responsible for a thousand-page manual no longer works. One writer can't scale to support an entire community of diverse developers. She can't predict all of the different types of code they'll be trying to write, and can't anticipate all the ways they'll get stuck. So we have to change the way we approach documentation.</span></div><div style="font-family: inherit;"><span class="Apple-style-span" style="color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;"><br />
</span></div><div style="font-family: inherit;"><span class="Apple-style-span" style="color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;">One of the most important roles of the official documentation is to introduce libraries, features, and tools for the first time. When there is no other existing documentation, people will read your docs. That will always be true.</span></div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;"><span class="Apple-style-span" style="color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;">After people have noodled on your docs for a while, and figured out how to do what they're trying to do, they'll become a strong, capable, worldwide team, skilled at helping specific slices of audiences do exactly what they're trying to do. That's the power of the community.<br />
</span></div><div style="font-family: inherit;"><span class="Apple-style-span" style="color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;"><br />
</span></div><div style="font-family: inherit;"><span class="Apple-style-span" style="color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;">And that's where our jobs as tech writers change. We're writing docs, to be sure, but we also need to help the community support itself. Let people help each other do tasks similar to the work they're doing themselves. Cultivate a community of helpful developers, and give them easy ways to share their knowledge. Make sure that helpful pages, responses, and code snippets are surfaced in search results, give pointers to the best ones in the docs, and give credit where credit is due. Because lots of heads are always better than one.<br />
</span></div>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-3743033843770509752011-09-14T15:06:00.000-07:002011-09-14T15:06:42.315-07:00Evolution of Tech Writing: Where Do We Go From Here?<div style="font-family: inherit;">In the usability studies we've done here at Google, we've found that developers are less and less inclined to read the "official" docs by default. Rather, their first step is to do a Google search for the information they need. Often, people turn to forums, blogs, and wikis to figure out how to do what they need to do. </div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">This fundamentally changes the developer support model. From the point of view of developers, it leverages the brain power of a community of developers who are all trying to accomplish similar objectives, and can learn from one another. </div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">For an organization offering APIs or developer tools, this enables developers to support one another, which is infinitely more scalable than trying to support all developers from in-house.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">For those of us who are involved in developer support, this represents a powerful shift in how we approach our roles. This is especially true for tech writers.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">Tech writers represent the point of view of our developer community. At the same time, we are internal to the company and have a direct connection to the teams who create the APIs. </div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">We can use this intermediary position to identify, and then publish, valuable information that developers would have trouble figuring out on their own. For instance, we are uniquely able to write documentation like:</div><ul style="font-family: inherit;"><li>A developer's guide for a new API that explains what a library of calls is meant to do, and how to combine the methods in a logical way. </li>
<li>Sample code that shows how to approach a particular task in an efficient and sanctioned way. Bonus points if this sample can be compiled and run, so someone can copy it and use it as the starting point for their own application. </li>
<li>A reference guide that gives default values and acceptable ranges for arguments, and explains unpredictable side effects of calling a particular method.</li>
<li>Cross-product documentation that explains how to use one library in conjunction with another.</li>
</ul><div style="font-family: inherit;">A tech writer's role is bigger than documentation. We know what our developers are trying to accomplish, and can advocate on their behalf to make those things easier and more achievable. We can influence the product teams on all levels, from creating a library of calls that is better architected and easier to understand, to writing APIs that use more understandable signatures.</div><div style="font-family: inherit;"><br />
</div><div style="font-family: inherit;">Tech writers have a unique and irreplaceable role, and always will. The explosion of information and support now available on the internet helps us capitalize on our unique strengths. It frees up our time to work on the things that really matter, which makes us more valuable, and makes our jobs much more interesting. It's a good time to be a tech writer.</div>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0tag:blogger.com,1999:blog-8697250739221355102.post-43386164161121441392011-09-14T15:04:00.000-07:002011-09-14T15:12:10.826-07:00Welcome!<div style="background-color: transparent; font-family: inherit;"><span id="internal-source-marker_0.024197357706725597" style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Hi! I’m Jen. I lead the Developer Documentation team at Google.</span><br />
<br />
<span id="internal-source-marker_0.024197357706725597" style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">My team is part of Google’s Developer Relations team, which helps people use Google’s developer products and APIs. The tech writers on my team provide proactive support to Google’s developer community. We collaborate with engineering teams as they create APIs and developer tools, and put ourselves in the shoes of the eventual users. We think about what works well, and where people might get tripped up. In some cases, it’s possible to preemptively fix the problematic bits before an external audience ever sees them, in which case we advocate for doing so. In other cases, we write developer’s guides, tutorials, complete reference documentation, and sample code that help developers do what they set out to do.</span><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;"> </span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Myself, I’ve been in the tech writing field for about 15 years. I wrote developer docs for around 12 of those, including for 3 years at Google. I got to the point in my career where I wanted to make an impact in a different way, and gradually transitioned into a management role. I’ve been here for the last couple of years.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">I decided to start a blog as a way to organize what I’ve learned during my tech writing career. I’ve been fortunate to work with some great mentors and have learned a lot. Perhaps my blog can serve as a surrogate “mentor” to others.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">I hope to garner community participation, feedback, and debate (of the non-snarky variety) on the things I post here, so that I can further learn from the wisdom of the masses. My greatest hope is that the discussion that results from my posts will add more value than the posts themselves.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">I would also offer this blog as a resource for answering questions from you, my readers. If you’re facing a particular documentation or management issue and would like to get my advice, and the advice of the community of commenters, please send me email from my </span><span style="font-size: small;"><a href="https://plus.google.com/106258380218567160277/about"><span style="background-color: transparent; color: #000099; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: underline; vertical-align: baseline; white-space: pre-wrap;">Google Profile</span></a></span><span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;"> page. Note that by doing this you’re implicitly giving me permission to publish the contents of your email. It'd be even better to let the readers of this blog know who you are, too, so unless you’d prefer to remain anonymous, please include a link to a site that tells us more about you.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Although I currently work for Google, the learnings and opinions I express in my posts were garnered from my entire career as a technical writer. No one else necessarily agrees with the opinions I express here. </span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Welcome to my blog! I hope you enjoy your stay here.</span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">Jen </span><br />
<br />
<span style="background-color: transparent; color: black; font-size: small; font-style: normal; font-variant: normal; font-weight: normal; text-decoration: none; vertical-align: baseline; white-space: pre-wrap;">PS Why is this blog called WTFM? Well, we tell our readers to RTFM, so I guess that makes it my job to...</span></div>Anonymoushttp://www.blogger.com/profile/12288992150223795528noreply@blogger.com0