|
|
Mostly podcasts about documentation, technical writing, and technical editing.
-
Download the episode
Duration 3:11
Size 2.5 MB
Sometimes there are a lot of little notes that can be written about a feature, and sometimes features do several different things. Is it always best in an overview topic to document it all comprehensively?
|
-
Download the episode
Duration 20 minutes
Size 14 MB
Mike Pope, a technical editor with ASP.NET, and I talk about working with new writers. And just technical writing and editing in general.
Mike, you SO need to start your own podcast! You have a venerable blog already. I know you have a nice recording device...
P.S. I hope you don't mind I nicked your picture off your blog.
|
-
Even though I really like concise writing, sometimes the whole story has to be told.
Download this episode
Duration 3:16
Size 2.3 MB
|
-
-
I'll be hosting a springboard session at the STC conference next week. Springboard sessions are informal discussions around whiteboards or flip charts where people can capture ideas. Mine is about using multimedia as part of a documentation set, which is something I've been working on part-time for the last year or so. The session is Monday from 10:00 to 10:30.
Here are some examples of topics in the Visual Studio Tools for Office documentation that Kathleen McGrath and I have created videos for. Inside the topic, there's a link to a video demonstration that takes you to a Visual How To page on MSDN, where you can watch the procedure and get an idea of what's going on before you start working through the steps yourself:
Walkthrough: Automating an Application from Controls on the Ribbon
How to: Add a Custom Task Pane to an Application
Automating PowerPoint 2007 Using a Custom Task Pane
Here's an informal presentation I did that's just audio:
Audio How-to: Customizing the Ribbon Using VSTO 2005 SE
I'd really like to see what other people are doing and talk about what works and what lessons we've learned. Hope to see you there!
|
-
I've been having a short discussion with Tom Johnson at I'd rather be writing about the new format of his podcast tech writer voices, and he asked about what I've been doing. My response got kind of long, and it's stuff I've been wanting to post here anyway, so I decided to write it up.
Several factors kind of came together for me last fall:
Tom Peters's work on personal branding (for example http://www.fastcompany.com/online/10/brandyou.html) and the Personal Service Firm (PSF) idea (http://www.tompeters.com/blogs/freestuff/uploads/PSFIsEverything.pdf).
Richard Florida's ideas about the rise of the creative class (for example http://dir.salon.com/story/books/int/2002/06/06/florida/index.html).
Daniel Pink on the free-agent nation and the rising importance of creativity http://www.danpink.com/pink.php.
Most of my life I spent in school, working minimum-wage jobs with bad managers to pay bills. Both of these environments work best when there is no individuality in the way you memorize the lessons or make the sandwiches, and I did really well in them. I figured I had my band during my free time, where I could channel all my creativity and ideas--it didn't really occur to me that I should be doing it at work too. Even after I became a professional technical writer, that old restricting paradigm was in the back of my head.
If you think about the future of your profession (pretty much any profession these days), the ideas in those books will shake you up a bit. So I thought about what I wanted my brand to convey, you know, just in case. I started along the lines of "I make sure technical documentation is the best it can be," and then I started tracing how to do that.
I had to understand learning theory and how the brain works. How to design information so that it matches reading/skimming/learning behavior. Ways to get and hold attention in the attention economy. Using story to help people understand and retain the message. (For a good, practical overview of a lot of these ideas, check out the book Made to Stick.)
Before long my brand had morphed closer to "I help you shape your message so the audience gets it. Really gets it." I don't have it worked out yet, but that's pretty much the idea. :-) It turned out that what motivates me, and what I love about the job, is not so much creating clean copy as creating effective communication.
This concept of what my personal work really is opened me up to seeing ways I could contribute beyond editing text. Editing text is still extremely important, but I started thinking that, really, if what we want to do is to get users the information they need when they need it in the best format--there can be more to that than putting great docs in the box and on the Web. It goes beyond just giving information to users, too. Tom talked about Help 2.0 on his podcast, and Andy Oram has a great article Rethinking Community Documentation. This idea really encourages community storytelling, in the sense of getting developers to tell stories about their experiences in a way that can help others when they encounter similar situations.
So there's that, and work has been pretty busy. :-)
|
-
A writer who used to be on the Visual Studio Tools for Office team, Kathleen McGrath, is finishing up a book about VSTO. She talks about how writing a book is different from writing documentation that is part of a product, how she starting working with the publisher, and what the writing process is like for books.
Kathleen's Blog
This podcast is 9 MB in size, and is 11 minutes, 49 seconds long.
Download this podcast
|
-
I have recorded episodes with two of the writers on the VSTO UE team (McLean and Norm), and here is the third writer, Brett Samblanet. We talked about the writing process, how Brett became a writer, how school prepared him for his work, and the importance of being able to communicate well and to take criticism.
This podcast is 8 MB in size, and is 11 minutes and 32 seconds long.
Download this podcast
|
-
If you take on projects outside of your basic job description, chances are some of them won't work out the way you wanted them to. Generally that isn't too much of a problem around here--nobody should be sticking right to the basic job description, and not every project can succeed. But you also have to work at minimizing the risk.
Last week, Ann Beebe talked about success. This week she talks about the other possibility.
This podcast is 5 MB in size, and is 6 minutes, 12 seconds long.
Download this podcast
|
-
Writers can increase the value of their documentation by visiting customers where the customers work and seeing what they are doing. It's easier to write targeted topics when you know what readers need.
Ann Beebe, User Education manager for Visual Studio, gave me two examples of writers who went into the field and discovered how the customer's experience can be very different from the experience in the development team.
This podcast is 6 MB in size, and is 8 minutes, 29 seconds long.
Download this podcast
|
-
I got a great request from John in a comment. He suggested blogging about how technical writers prepare their first drafts--how they get started creating a document out of a bunch of facts and features. That's such an interesting topic I'd like to get as many people as I can to talk about how they do it.
I start with my own experience and then talk with two of the writers on my team, Norm Estabrook and McLean Schofield. The drafting process for each of us starts with gathering all the available information into some central location and then organizing it, but we each have our own methods for gathering and organizing.
This podcast is 9 MB in size, and is 12 minutes, 3 seconds long.
Download this podcast
|
-
It seems that there are not a lot of writers with programming experience who are looking for a position in a big company. But there are jobs available--a search on the Microsoft career site for the job title "programming writer" returns 24 results as of August 15, 2006. My team has been looking to hire a programmer/writer for a number of months. To give you an idea of what the position (and interview process) calls for, I intervewed my manager Christa Carpentiere to find out what she's looking for in a writer.
I also talk a bit about the desirability of working for a corporation versus being self-employed, but only from the perspective of what I've read--I've always had company jobs. Do any of you readers have personal experience you could share about this?
This podcast is 8.5 MB in size, and is 12 minutes, 6 seconds long.
Download this podcast
|
-
Marketing provides the product content that customers read first. This content introduces customers to features, to actions, and to parts of the user interface. Customers will then expect to find those things in the documentation, using the terminology they read in the marketing materials to search the contents or to check the index.
For example, if the Web site says "Publish your documents using the Simple Deploy wizard from My Servers," users will look for documentation about publishing, about the Simple Deploy wizard, and about the My Servers section of the UI. Does the documentation use those same terms? If any names were changed by the product team or by marketing, were the new names communicated to everyone in time to use them consistently? Even though the marketing team and the writing team generally move in different circles, each needs to pay attention to what the other team is doing.
To get a perspective on marketing as content providers, I talked with Mike Hernandez, the product manager for Visual Studio Tools for Office.
This podcast is 7 MB in size, and is 9 minutes, 11 seconds long.
Download this podcast
|
-
Graphic artists and designers are an important part of documentation, but until lately I didn't look into that side of communication very much. After I talked with Monique Bailey, our documentation designer/artist, about how to think visually, I wanted to get a better picture of the designing profession. I went back for an interview so I could ask Monique about her work, and how she got involved with technical design.
This podcast is 17.4 MB in size, and is 24 minutes, 41 seconds long.
Download this podcast
|
-
I want to use more illustrations and other graphics in our documentation. Graphics can help clarify ideas that are hard to understand from textual explanations, they can add useful redundancy to the communication, and they provide more learning channels. Plus they're often fun to look at.
The documentation I've worked on hasn't used graphics or art much, so I'm not used to thinking visually. That's not a Microsoft thing, it's more the style of the individual writers (like me) who generally think in words. In fact, Developer Division User Education has a designer/artist, Monique Bailey, who creates art for the docs (among her other design duties). To get a better understanding of this important area, I met with Monique to talk about how to turn concepts and ideas into pictures.
This podcast is 7.16 MB in size, and is 10 minutes, 25 seconds long.
Download this podcast
|
|
|
|
