Monthly Archives: February 2009

techpubs

Managing Writers book includes well-earned experience stories

Richard Hamilton’s new book, Managing Writers: A Real World Guide to Managing Technical Documentation, is clearly organized and a fast read. It often reads like a reference guide, a book you could keep on your bookshelf for years to come.

It is a reference guide in my view, because you can go straight to the table of contents and pick from the list of topics. Want to get your arms around people? Refer to many chapters on Managing People. Need to know insider information on projects before it spirals out of control? Stop the spin machine and go to the pages about Managing Projects. Wondering if the latest alphabet-based tossed salad of acronyms will actually solve your user’s information problems? Hightail it to the Managing Technology chapters. Each of his chapters offers the depth and detail you’d need when faced with a situation you hadn’t seen before. For example, if you’re new to Localization, the information offered will help you ask the right questions and help you get started while avoiding headaches and “time sinks.”

As I read through this book, I felt like I was having a nice long lunch with one of my favorite managers. It’s sprinkled with stories and phrases like “gold-plated Cadillac.” I enjoyed reading about his path to technical publications. It seems many people are eager to leave tech pubs once they start in it. Richard didn’t know much about tech pubs, and wondered if he was leaving the world of technology, but accepted a position anyway. He was willing to learn and stay with it. And stay with it he did, for many years beyond the first two he promised to the hiring manager.

Whether you’re already managing a handful of writers or just starting out, or if you’re hoping to move towards management in technical publications, I think you’ll find this book helpful. Even an experienced tech pubs manager will enjoy hearing another’s perspective and will find many familiar themes that match their own companies and product documentation.

Scott Abel had three copies of the book that he was giving away on Twitter last week – get one before they’re gone, or buy your own copy to read and then keep on your shelf. Like I said myself on Twitter when I first read the book, thank you Richard, for no cat herding references.

techpubs wiki

User-generated content versus community-generated content

I think there is definite triangle emerging in my mind when I try to notice differences in quality and time-to-market and cost for user-generated content and community-generated content.

To me, user-generated content is the type of content you find in forums and mailing lists. It is likely to show up on a search for information and troubleshooting. User-generated content varies widely in quality and may be outdated quickly. Usually readers of user-generated content understand “Caveat Lector” – Reader Beware.

Community-generated content has a different quality bar, in my mind. While a community may be defined with a mailing list as its only communication, more likely the community is not using the mailing list itself to offer how-tos or detailed troubleshooting. Instead, a community, since it is defined with a common goal, may have content creation as one of the means to achieving that goal.

So which is faster? User- or Community- content?

I believe that individual users are faster at posting informal, conversational responses to specific questions. But a community may have a more thought-out approach to the big picture of what needs to be created, content-wise. I am not just talking about written content, although of course FLOSS Manuals is one of the communities I’ve had direct experience with. I’m also thinking of WordPress.tv, where the site was “seeded” with twenty or so professionally-created video tutorials, but then the community members’ contributions were also accepted. While it may take a while to create that content, and it might not have a professional voice-over, it is good enough to help another community member learn a particular WordPress technique.

Good enough content

Both types of content often offer “good enough” answers to questions or advice about a best way to proceed with a particular solution. Good enough is judged by the reader. I don’t think that I’m calling one type of content more professional than another. Rather, the usefulness of the content vetted by a community is the criteria for judging its quality.

What do you think? Is there a distinction to be drawn between user-generated content and community-generated content?

blogging DITA OLPC techpubs tools wiki

What is Anne Gentle up to?

I finally feel some energy returning after my eye injury about a month ago, although my right eye remains dilated which still means that side is a bit out-of-focus and I don’t like driving at night. I feel like I need to give a status update or some such. So here goes.

Winter Camp

boxartWith luck my eye should be just fine in time for a big event coming up: Winter Camp 09 the first week of March. I’ll be representing and working for FLOSS Manuals at this event, held in Amsterdam. From the description, it will be an amazing week:

Network Cultures Winter Camp will be a mix of presentations and work spaces with an emphasis on getting things done. It will be a four-day program of work spaces and plenary presentations, in which a dozen networks (each of which has 5-15 people) can work on their specific current topics.

The format was inspired by a cardboard box art installation that activates a temporary warehouse of contemporary knowledge from what I can gather from a translation of the page, Re-fitting ideas. Come on, that’s incredible. I am so thrilled to be a part of it. And I know it’s going to be a week of hard work.

Preschool website completed, using WordPress 2.7

We’ve also finished the preschool website I mentioned in my interview with Michael Silverman of Duo Consulting. We used WordPress hosted at Midas Networks. I recorded some screencasts with Jing to show other parent volunteers how to edit content and work with images. All the photos on the site were taken by parents so it’s quite the “do-it-yourself” website. I am hoping that WordPress 2.7 will be easy enough for even those in our volunteer and staff group who are not technically savvy but still give us the growth towards more content creators that we have in our goals for the site.

FLOSS Manuals and OLPC

We’ve sold over 200 copies of the OLPC Laptop Users Guide on Lulu.com, and Adam Hyde gave a copy of one of FLOSS Manuals’ books to Bob Young, the CEO of Lulu, while they were at the O’Reilly Tools of Change conference. Impressive. I still plan to make the Sugar Users Guide better. Adam Hyde and I are working on a book about how to run a Book Sprint in FLOSS Manuals, naturally, and we would welcome additional contributors.

DITA and Web 2.0

I’ve been approached to help put a public face on standards for DITA and Web 2.0 projects such as DITA for wikis (an example is Lisa Dyer’s DITA2Wiki project on SourceForge) and DITA for blogs (another example is DITA to WordPress or DITA and microformats).

STC Intercom Editorial Advisory Panel

I’ve been pretty impressed with the STC Intercom issues in 2009 so far, but I wrote one of the articles so perhaps my judgement would be playing favorites. I would like to gather feedback from STC members and non-members who read the articles – how’s the content grabbing you this year?

Author-it 5.2

It looks as though 5.2 is the version of Author-it that will allow us to upgrade from 4.5. Our content just wouldn’t publish adequately (Word or HTML) on 5.0 or 5.1, but now that 5.2 is released, fingers crossed, we’ll be moving to 5.2 soon. I should write a blog post about some of our testing on our 20,000+ object database. I’m getting used to the Ribbon Bar as I continue to work in Word 2007, and Author-it’s 5.x interface feels a lot like Word 2007.

Writing a book, do tell me what you want to know

Last but certainly not least, I’m working with a professional editor to try to finalize my book about documentation as conversation that examines the power of social media for writing projects. It walks through the myriad of possibilities of different types of social media tools and analyzes how writers and communities are using these tools for technical documentation. Look for it this spring!

techpubs wiki

Understanding foundations before tools

I’ve been following the latest Book Sprint at Eyebeam in New York City with interest as it is a bit of a unique project. They took a textbook that used all proprietary software for the exercises and examples, and re-wrote the book so that the exercises can be completed using all free software instead. Think of students shifting from Photoshop to GIMP, and seamlessly moving to InkScape from Illustrator.

The book was originally collaboratively authored in a wiki, and FLOSS Manuals got approached to take the textbook and turn it into a proprietary-software-free resource.

The introduction to the Digital Foundations book describes so well a typical student’s approach to learning.

This book was written by two artist educators who teach digital art and design studio foundation classes. While teaching classes that take place in software laboratories, we noticed that many of our students expected to learn to use software, but gave little consideration to aesthetics or art and design history. A typical first day question is, “Are we going to learn Photoshop in this class?”

According to Michael Mandiberg in “On collaboration,” as he was preparing for the Book Sprint he has a lot of thoughts about collaborative authoring, and I found it well worth reading. But I also noted his elation that “We have secured the first Creative Commons license from Peachpit/Pearson. (CC+, BY-NC-SA)” I love the spirit of openess represented from a publisher willing to experiment. This Book Sprint is such a neat example of what collaborative efforts can accomplish. Photos are found at http://en.flossmanuals.net/about and I like the energy shown in this one.

Sprint!

Eyebeam in NYC
This is what a sprint looks like when you’re there in person.

Wiki quickly!

FLOSS Manuals wiki interface
This is what a sprint looks like on your computer if you’re participating remotely – you’ll see your name next to one of the “chapters” or “topics.”

If you want to experience this type of authoring sprinting for yourself, get involved with the next FLOSS Manuals Book Sprint where we’ll be working on a book for the Firefox browser. The sprint is March 17th & 18th in Palm Springs, CA which will be lovely that time of year. It’s being held in connection with the Documentation and Training West conference, aka DocTrain West. Scott Abel is offering free conference registration to Book Sprint participants who stay in the conference hotel.

DITA OLPC wiki

InfoSlicer is released to the world

Let the remixing begin. I just got word today that the Infoslicer project has been checked into the Sugar code repository at http://git.sugarlabs.org/projects/infoslicer, and released under the GPLv2 license. Can I get a whoohoo? Oh yeah!

Infoslicer is a Sugar Activity that enables students and instructors around the world to assemble Wikipedia articles into new information packages. Under the covers one of the technologies that makes this possible is the Darwin Information Typing Architecture (DITA). I first wrote about the InfoSlicer last fall, in Wikislicing project gets real – introducing InfoSlicer as a Sugar Activity with a picture of students using scissors to re-assemble Wikipedia articles.

If you want to download the Activity to your XO or another computer with Sugar installed (here’s how) to try it out yourself, go to http://sugarlabs.org/go/Activities/InfoSlicer and install the Activity (here’s how).

I have downloaded it to my XO in anticipation of showing it off at the next XO Austin Users Group meeting and the install was straightforward. I’ll get it on a USB stick to share at the meeting (2/16 at Central Market on N. Lamar in Austin at 6:30). Here’s a screenshot – and be sure to check out the YouTube video!

infoslicer

Laura Cowen notes that the xo package that you download doesn’t contain any sample articles from Wikipedia (which ideally it would to help you get up and running more quickly using the tutorial). You can use InfoSlicer without these sample articles (you download Wikipedia articles from within InfoSlicer anyway). If anyone is able to re-compile the xo package with sample articles in it, Laura can provide instructions on where to put the sample articles in the package so that InfoSlicer automatically picks them up when it starts. Who wants to create the wikislice seen ’round the world?

Digital diets and media consumption

Light posting for me at the Duo Consulting blog over the last few months, but I did want to share these two.

Will You Go on a Digital Diet in 2009?

Ah, 2009, a new year and a new start, including resolutions to improve oneself. Let me guess, you want to save or make more money, lose weight or increase fitness, or manage your time more effectively. You and the rest of us! Let’s talk not about food consumption, instead, let’s talk about your media consumption. And while we’re at it, let’s recognize that we’re all offering media. According to the 2008 Media Report from Future Exploration, everyone’s a media mogul. Especially interesting to me is user-generated content. Participatory media is resulting in a nearly infinite supply of content, although the increased fragmentation of attention is certainly an implication as the report points out. They also think that Pro-Am (professional-amateur) content models will emerge, a model in which I’m very interested. Read more…

Some Eyeballs and Eardrums Are Worth More Than Others

While watching Top Gear on BBC America, I shop for an “I AM THE STIG” t-shirt on the BBC America website as a gift for my husband. While reading Real Simple magazine, I watch Clean House on the Style channel and plan a trip to The Container Store for more storage bins for toys and clothes for my kids. It’s a wonder I can pay attention to all of these messages, yet I am making decisions based on my media consumption. Read more…

techpubs tools

Author-it and MadCap Flare comparison

I’ve had more than a few questions asking for a review of Author-it or MadCap Flare or a comparison of both. So I decided to do some homework. Initially, I wasn’t sure why they are categorized together. Is it due to the price point? Or is it due to the single-sourcing all-in-one software package aspect? I suspect it’s the latter since the former seems more disparate lately.

Let’s examine the single-sourcing aspects.

Both MadCap Flare and Author-it only work on Windows for authoring (but both offer cross-platform and cross-browser output).

Both MadCap Flare and Author-it output to printed and online formats. These formats and the way they arrive at the output offer some differences, as seen in the “publishing aspects” section below.

Both MadCap Flare and Author-it have a single place to store source.

Both are sourced in databases. The single source for MadCap Flare is in a flat folder structure with XML files.  MySQL database. The single source for Author-it is in either a free Jet/MSDE/SQL Express database for up to 4 MGB of content, or SQL Server.

Author-it only imports Word documents. Flare imports both Word and FrameMaker documents as projects.

What are the publishing aspects?

Author-it uses Word templates for all printed page layout. If you’re well-versed and experienced in Word for page layout, this product works for you.

Author-it uses CSS for HTML layout, but some layout and graphics are controlled in different areas. I had to uncover the locations for each graphic and CSS area recently while customizing the HTML output for the One Laptop Per Child project. In my experience the HTML layout was all over the place. From templates to stored objects to files stored locally to certain aspects changed within a dialog box on a template, I felt like the online layout was a bit scattered.

Here are links to their Knowledge Center articles that were helpful: Customizing Related Topics in HTML, Adding a Customized HTML Template, and Using a Customized HTML Frameset. I muddled through somehow, and I don’t have a good comparison for MadCap Flare’s HTML output.

Keith Soltys has a nice Review of MadCap Flare from summer of 2007 that shed some light onto the publishing and he speaks highly of the layout rendering nicely in both FireFox and Internet Explorer. It’s interesting, though, that he’s evaluating Author-it as well, so I guess these two products are often compared side-by-side.

Apparently MadCap Flare uses CSS for all layout aspects including print. The new Blaze announcement offers a non-Frame and non-Word reliance for actual PDF or print output. The reliance on CSS (Word’s interpretation of CSS has its limits) may have forced MadCap to create Blaze. Anyone else think you should wait for the CSS 3.0 specification before really nit-picky print layouts can be accomplished? Or is CSS ready for this level of design? I know with the OLPC project, we’d love CSS layout for really nice ebooks, so maybe MadCap is onto something with CSS for print layout.

I’ve written up this comparison because many people have asked me for it, but I know it’s lacking. Please, feel free to fill in the gaps that this post has so that others may fairly evaluate each tool in their environment.

I had an email conversation with Kai many months ago, who was a good sport with all of my questions regarding the content and priorities with that content. He realized, though, that Author-it was probably eliminated due to its use of SQL Server – they wanted a MySQL database container for their content. So I figured that MadCap was their final answer. It is so interesting how the final decision can be dictated by the underlying system requirements. One of the commenters on Gordon Mclean’s post, Why AuthorIT? (sic, they’re now Author-it) was seeking a similar authoring tool but on a Mac platform.

Sorry Kai for dropping the conversation for so long. But please do share your experience with the tools since then.

techpubs

Examples of blogs as online help and release notes

I’m always on the lookout for examples of social media tools used to write and maintain online help. One trend I think I am seeing is the use of blogs as the basic release notes for new features in products, especially web applications. Examples are new Google Calendar features and SmugMug, where the entire blog is dedicated to Release Notes.

I’ve also found the Jing online help is written and maintained in Movable Type, a blogging tool. Many blogging tools can be used as content management systems, and it appears that Jing’s writers see blog engines that way too. There are lots of nice built-in features that they are taking advantage of – a nice Search field at the top of every page, and the Categories link at the bottom of each help topic give a nice collection of topics. There’s only one “table of contents” for the help system, and that’s the top page, but it works nicely as a site map. The overall effect is a very simple and elegant user assistance or support system. One detail I did discover while trying out the site, though, is that the MT search engine did not find hits for a search on “mpeg 4″ when the topic titled contained MPEG-4.

The use of a blog overall seems like a great idea for release notes – give your product some Google juice and search power as well as generate buzz for new features by giving other bloggers a well-understood infrastructure to link to you and give your entries trackbacks. If your release notes contain a lot of bug reporting or issue fixes, I’m not sure a blog is a good match since that’s not exactly a positive spin on your product release. Then again, sometimes transparency and honesty is the best policy. What do you all think?

techpubs

Preponderances prior to the STC Summit

Like Tom Johnson I’m happy to embrace the recording and re-broadcasting of the STC Summit this year. To me, this makes the STC Summit much more like SXSWi where you go for the people instead of just the programming. My hope is that instead of being concerned with missing certain sessions, I can use my time in Atlanta to fill in the conversations I have on social networks (blog comments and Twitter) with real-time conversations and networking.

Content capture and release

I’m both professionally and personally curious about how or if this move affects attendance at the Society for Technical Communication annual conference. I’ve asked around at work (remember that I’m an association techie geek, or at least I work with some real association pros) about some of the trends in the association marketplace.

Update: I spoke to Lloyd Tucker this morning and got additional details about STC’s plans for the recordings. We geeked out about association management technology for a while and it was great. :) I should have practiced better citizen journalism and talked to him yesterday, and then published this post, so I apologize for the interruption in the post, but I’ll summarize some of the details here. The questions are in bold:

What’s the copyright or licensing agreement for the recorded content? The speaker agreement, which will be sent to all speakers, states that the speaker grants STC rights to a royalty-free license of the presentation. In exchange for presenting, speakers get full or partial registration compensation (depending on whether you are the sole presenter of a session). The speaker retains copyright of the presentation (slides and audio) and the speaker can use the material however they like. Now, because the synchronized slides/audio recording is on a website and can only be viewed there behind password protection, a speaker can’t download and redistrubute a synchronized recording, but speakers can download an MP3 recording of their session and give that away with their slideshow if they choose to. See next my question.

Are the recordings proprietary formats only or can people get MP3s to load onto portable devices? With a password to the recordings, you have the option to download any presentation as audio and take it with you to the gym or in your car, or if you are a speaker and hold the copyright to the content, you can upload it to your blog or website. You can also download a PDF of the slides from the password protected site, so you have the makings of portability of the content.

Is there any “right of refusal” built in if someone doesn’t want to be recorded for any reason (or certain reasons)? Lloyd really wants everyone to participate in the recordings, but would consider individual cases with special needs. If you don’t want to use the pre-configured capture laptop they’ll supply, you can install the recording software on your laptop. The recorder records everything displayed on the screen. There are certainly sessions that won’t be recorded because they are progressions or otherwise not a good match for recording. They do plan to have audience mics in some rooms to record audience questions, although speakers should also repeat the questions.

How can STC afford this previously unaffordable technology? Last year, STC’s home grown in-house conference management system (DOS-based) broke so badly that they decided that repairing it was not an option. The budget cycle and some timely action from the board of directors aligned just right with this need for an updated conference management system. The ease and flow of the web-based proposal management process gave them an immediate efficiency boost, and they are able to publish the preliminary program earlier than ever, plus output it to multiple formats allowing them to publish in STC Intercom easier than before.

And of course, what’s the price point? :) This is the main question that associations have to consider carefully. Lloyd says they haven’t set a price for access to the recordings yet. The vendor doesn’t have a way to “group” recordings so that you could buy only a certain track – it’s all or nothing. Lloyd currently thinks the price for recordings for non-attendees will be comparable to the full registration price. It is a ton of recordings, when I look at the program. While I didn’t ask him specifically, he didn’t say they were considering a fee difference for members and non-members to purchase access. He’s not sure if there will be a different pricing structure for individuals and groups (the scenario Mike gives in the comments). In case you were wondering, for the most part, associations haven’t found that offering recordings causes conference attendance to decline. Lloyd also said that he hasn’t thought of directly comparing proceedings to this new recording offering – because proceedings are usually either articles or academic papers, more of an archive or record of presentations, and the article may or may not reflect all the content of a session. I’d say it’s generally tough for STC to find pricing “comps” for their relative size. I did mention that I have to budget for about $950 to be there even with a compensated registration, so if one could buy the recordings for 15-25% off of the registration fee, it could be worth it even for a single working tech writer.

End of the update! Thanks for reading.

Associations vary greatly in their membership guidelines, open or closed stances on sharing content, and in how they pay their bills to keep offering member servies (non-dues revenue is a big part of this equation.) In STC’s case, the tool they will be using is Live Learning Center to record all presentations and serve up the descriptions – the preliminary program is available online already. I’m presenting two sessions: Documentation with Wikis, Blogs, and Online Communities with Janet Swisher and another one about collaboration techniques where I’m still toying around with a title, description, and outline.

Overall, I’m really pleased they’ll be recording sessions (audio and screen only, not video), but not sure how other associations are handling this sort of content dissemination and how well it’s working. What are good and bad outcomes from this shift towards offering asynchronous conference attendance? Here’s some of what I’ve learned.

Do printed proceedings and audio recordings represent the same value?

Proceedings have historically been sold by professional organizations. I learned that the heart of the issue is what do you charge, and do you charge members and non-members differently? Printed proceedings are the model they seem to be using though. With the upsurge of all this community-generated content, The answer varies widely because of the different cultures that each organization embodies. And associations are finding it harder and harder to justify any additional charges.

Some of the reason for this shift in expectations are other examples that are changing the way we think about conferences and availability for viewing sessions asynchronously: namely WebStock, SXSW Interactive, and TED. Many of their speakers are compensated at greater rates than any of us would be at STC conferences. Having a recording that you can then send people to as a “portfolio piece” makes sense when you are a paid speaker. You’re glad to have others have free access to it without having to incur the expense yourself of creating a recorded portfolio piece. I know I’d prefer it if I kept copyright of the content, but I haven’t seen the contract yet to know whether STC gets a one-time broadcast “license” to the content. Then again, the trade off there is that STC would be locked into proprietary broadcasting technology (which they probably are already).

I know that WebStock offers their recordings for free, but they have a group of volunteers (looks like about five people) who offer them as a labor of love (though I’m sure love doesn’t pay the bandwidth bills). For a conference with 500 or so attendees, that method is probably the only one that makes sense from a cost persepctive. They are also allowing refusal to be recorded for any reason – and don’t even expect you to give a reason. I’m learning this interpretation from this post to the WebStock blog. Associations don’t really adhere easily to this model, although an association that had members who were willing to labor that much would be a great association indeed.

SXSW Interactive has offered recordings for years now but they are also attended by over 6000 most years (I think it’s a slow year when it’s in the 3-4k range but feel free to check my numbers) and they even have an artist doing an artistic rendition of the session (see honoriastarbuck.com). I’m not entirely sure how their cost structure works. It full well may have been done by volunteers in the early days. Heck, sched.org did their SXSWi demo for free last year and totally reaped the benefits (though they are looking for a sponsor for 2009’s SXSWi. Again, SXSW Interactive is not an association, does not have members, and is hardly comparable to an association’s annual conference.

And then there’s Technology, Entertainment, and Design – TED – I don’t know a lot about it, other than it’s 20 minute sessions and only last year opened up the recordings to the world. Their value proposition is inspiration, but they do have over 110,000 members in the community according to the website. They remain super elite and closed in the conference itself, but the content is open via video sharing. I can hardly compare a TED conference with a conference for a professional association, though, so I’ll stop with that.

There are neat examples out there of hybrid techniques, though again, not offered by an association. For example, the User Interface conference site has podcast interviews with presenters but also sells PDFs of their procedings at probably 10% of the price of the full conference. This method gives an audio experience for free, promoting speakers while still protecting the content that is specific to the conference.

How long will you be face-to-face?

I wonder how offering this audio will affect the number of days even registered attendees stay at the conference. As a mom, I know I try to keep my nights away to a minimum. Will my presentation schedule allow me to spend a few days in Atlanta and then somehow carve out time listening to sessions after my kids go to bed upon returning home? Or will I seriously make the time to close my office door, change my IM status to “watching recorded STC Summit sessions” and hunker down in front of my monitor with headphones on and attention fully watching and listening to sessions I missed?

Value propositions

So is the only value proposition for holding a conference the face-to-face networking? Or is there also the value of the content at the sessions themselves? For some reason, I still want to argue the case of the work-a-day technical writer who needs to learn new things as the main reason for them to go to a conference. Plenty of people use the “train a trainer” justification and send one writer on a team of ten and ask that writer to bring back all that they’ve learned at the conference and teach others. But more and more people have convinced me that you don’t need to go to a conference to learn. Having written the “Embrace the un” article and experienced firsthand the value of in-person connections, I ought to know this one by now. Yet I’m still writing justifications that seem to back different value propositions.

From my perspective, which is limited by age, experience, and the narrow working-mom window in which I live, offering audio is the right direction for STC to take. When I offer content for free on this blog, it has paid me back not monetarily, but in opportunity, connectivity, and learning I never could have gathered through other means. Will the “giveaway” of my session content at the STC Summit pay back in similar ways? I’m willing to experiment to find out. What do you think?