Monthly Archives: November 2009

Collaborative authoring – tools and costs

I’ve been working on some collaborative authoring scenarios for our Agile teams – we’re going from 5 people to 47 people in total who could author external or internal documentation within our two week sprints. Turns out, we likely represent some trends in the enterprise – Forrester just released a report about benchmarking your collaboration strategy.  A quote from the abstract does describe our need to broaden our collaboration to more and more people.

A companywide collaboration strategy was once a nice-to-have. No more. Even in the current economic climate, 37% of organizations surveyed in Forrester’s Q4 2008 enterprise and SMB software survey consider implementing a collaboration strategy important in 2009. Two broad trends are driving this: 1) There’s a critical need to drive information worker efficiency and to manage the unstructured content artifacts they produce; and 2) while the value of improved collaboration is clear, the path to success has become more complex.

Also, I’m finding that we have broader considerations than just the technical publications department for serving up the best content for customers. While researching some solutions, I discovered that most enterprise-level solutions would require a jump from four-figure annual costs (less than 10,000 USD) to five-figure annual costs (greater than 10,000 USD). Or, to go from four-figure costs to four-figure costs while still meeting the author requirements may require an open software solution.

I’m blogging about it because it seemed like an interesting phenomenon. I don’t usually like to write about tools, because I don’t want to seem like I’m endorsing a vendor. And I’m not endorsing any vendors, especially with the new FTC guidelines. But I thought by sharing this on the Internet, I might get some clarity on whether there is a true trend in the field of technical communication towards collaborative authoring environments, and perhaps discover what are the collective forces that are pushing us towards collaborative authoring.

First, some requirements for the system we need.

Consumer requirements

  • Must get a known version of the docs that were delivered with a particular software release
  • Must output printed books – PDF is fine, previously we used Word .doc files delivered in electronic format however
  • Must enable draft content to be available internally for review every week (even though we are on two-week sprints, three of six teams are on alternating sprints so once-a-week publishing, really once a day or on demand publishing would be required)
  • Many other items like syndicated content, comments, ratings, web analytics, but these are not “must haves”

Author requirements

  • Must fit into budget constraints (this amount is four figures currently)
  • Must meet the existing server and client system requirements (Windows-based, with a SQL Server installation available)
  • Must be supportable by three tiers: author community of practice, then the members of Agile teams, and then the corporate IT team
  • Must enable two authors per Agile team minimally (12-14), ideally allowing all 47 members of production teams to create content
  • Must enable concurrent use by authors in two different versions of the product

Possible collaborative authoring solutions

This list is not comprehensive, and I’m sure people would like to jump in with suggestions – feel free to do so. Remember that I’m in the “less than 50 users” category, and that the goal is company-generated user assistance articles, not community-generated articles. Authoring happens behind the firewall, but the content should be freely available once “published.”

Five figures:

Author-it Live: $30,000 (although their website is currently saying there are pricing discounts which make it about $15,000)

Sharepoint 2007 server: $40,000

Author-it to Sharepoint plugin: $25,000

Alfresco (compare to Sharepoint): $20,000 (blog entries hint at the cost)

Four figures:

Confluence: $2200 for 100 users or $800 for 25 users, annual cost (migration could be free depending on what tool you use to migrate content)

MediaWiki: free (migration would require WebWorks ePublisher)

WebWorks ePublisher: Server version $2000/year

Drupal: free (migration could be free depending on the method)


Migration is completely possible, when given the time to do it. We have over 4,000 HTML files on our helpsite currently. Interestingly, DITA could play into the migration scheme because it offers a universal “translation” like a Rosetta Stone, giving content some fluidity.

1. DITA2Wiki

This is an open source project that takes DITA output and transforms
it to Confluence Wiki, and it could be automated with builds. Download
it from

2. WebWorks ePublisher

This is a proprietary software tool that has an annual cost, available at I have a free version that I am using and it works, with lots of customization work in the designer we could get nice output, but at a cost. The Express version is $300 a year, but it would not give us the customizations on output that we would need. The Pro version is $800/year, giving us design, but not ongoing builds with the tool. The Server version is $2000/year which gives you designer plus a command line interface that could automatically build wiki output every time the product is built. WebWorks outputs to MediaWiki, Confluence, and MoinMoin. I have only tested output to Confluence, which works great.

3. Confluence DocImporter

This tool, Doc Import, is built into the Confluence wiki itself and offers a manual web-form-based import of Word documents. The pilot work I did worked really well. After we worked on a sidebar table of contents, however, no additional Word docs can be imported due to some setting where it won’t override existing pages. I would do more work on this method because the results are at first glance even better than those from WebWorks ePublisher. But, this method does not offer automation (unless we find an API that automates using  DocImporter).

4. Drupal’s HTML Import

This method is as-yet untried for our content, but the idea is that we could take our existing HTML output, which is pretty well-structured, and use the Drupal Import HTML module on the entire site, a section at a time. I think this method would work, although it is more than a bit labor intensive for over 4,000 HTML files and all the links and images involved.

Topic-oriented, web content

There are two other options that come to mind when mentioning collaborative authoring. They are at $390/year and Google Docs, with no price. But those options do not offer a topic-oriented content management system that you could use to output web content – instead you get bundles of PDFs or Word documents. I’m not sure either of those are viable for our requirements. But maybe I need to be thinking outside of the box?

What are some of your favorite collaborative authoring tools, and why?

Squeakland announces an Etoys book sprint Dec 7-12

Squeakland will have its first Book Sprint to create a Reference Manual for Etoys! Please join us online during the week of December, 7 to December12, 2009. The book will serve as

– the manual you can look up every part of Etoys,
– the documentation of what we commit to support in Etoys and
– the starting point for other, more elaborate materials.
For writing we intend to use FLOSS Manuals:

The manual will be available online (html and pdf format), and as a real book per print-on-demand. It will be licensed under MIT, so that we can also ship it within Etoys. We will work on it for a whole week from December, 7th until December, 12th. At this point, we are not planning a central in-person meeting, but the whole event will take place virtually on the internet. We will chat on an irc channel, and we will have audio chats every day to provide the opportunity for a talk. Of course, if you can organize a local meeting somewhere, that would be great!

You can find more information at

To join the sprint, please put your name on the wiki or send Rita Freudenberg a message.

Technical writers, web writers, jobs, and employers

I’m returning to and rereading Violaine Truck’s post to the STC France site of a review of Content Strategy for the Web. Before you read this post, it might make more sense if you go read hers. Take your time, I’ll wait. 🙂 After reading her post and then writing an overly long comment, I decided to turn my response into a blog post.

It all started with Twitter. Destry Wion’s tweet is how I found the book review, where he said, “Interesting review of @halvorson‘s book. As much an analysis of #contentstrategy in France as anything.” I am intrigued about the job market and the book itself, so I clicked through to the review.

Amazon tells me that my book, Conversation and Community, sells side by side with Content Strategy for the Web quite often. I am reading Content Strategy for myself and finding it complementary, with some concepts that are essential to understanding what is going on with the web. Thinking of a content audit on a single-sourced helpsite with 4,000 topics makes me want to cry inside a little. I say that only half-jokingly. 🙂

I read the review and my curiosity was piqued when Violaine said she’s a technical writer turned web content manager (with French job titles, naturellement). She asks in the introduction, “I hoped to find an answer in Kristina’s book to a prevailing question I (and presumably others) in France have: Is the title—Content Strategist—just a fancy name for one or more roles that already exist in the French job market…?”

I haven’t seen a job market yet where there is direct crossover between technical writing and web content jobs, yet in my book I believe in the future trends I see in technical writing and how we should be delivering our content with web content strategies adding value, especially for the social web.

Where are the jobs?

I have heard, “Where are the jobs that your book describes?” a few times since my book was published. I found one posting for a wiki writer that I blogged about previously. But I couldn’t directly point to specific job listings that combine all the skills and values my book describes.  I went to lunch with a community college professor here in Austin a few weeks ago. He is so inspired by my book that he wants to write curriculum around it, yet he correctly hesitates and waits to find the right job description to teach. At a community college, their professors know that you don’t propose curriculum until there are job descriptions in the market. It’s wise to do this in the community college setting so that their degrees match the demand for workers.

I think Violaine’s post helps us all get the perspective of a working technical writer. It’s a tough market out there. And it’s only getting tougher to prove value – no matter what your job description or title, or location, I’d say. Here’s my take from where I sit in the job market in Austin, Texas. There are plenty of technical writer jobs where a doing good, quality job is undervalued. There are plenty of web content creator jobs where good content is undervalued. Seems like everyone has to prove their value.

Consultants have this viewpoint all the time, that they must prove their value through metrics, return on investment, and so forth. It’s extremely difficult to act like a consultant in many jobs. If I’m reading between the lines of her post, it’s tough to be strategic when you’re copying and pasting, right? 🙂 I recently read a book called Corporate Confidential: 50 Secrets Your Company Doesn’t Want You to Know—and What to Do About Them. One mindshift that author tells you to do is to act like everyone is a client. You are the consultant.

Violaine has armed herself with the books that help prove a point – that a specialty does have value. It seems that’s only half the battle. The other half of the battle is to figure out where the value lies. Is it in business-to-customer interactions? Business-to-business? Is there a risk of inaction?

What are these jobs?

Finally, what are these jobs combining technical writing, content strategy, and web content? Colleges have web programmer classes and web design classes, because there is employer demand for those skill sets. I think there is an uncovered demand for web publishing and social web skill sets. In fact, I guess wrote an entire book about these skills. But just like technical writing, it’s difficult to teach, tough to evaluate, and often unfairly interpreted or undervalued in the marketplace. I think there are many job titles that fit that description. Community manager. Information architect. Technical editor. Program manager. Technical communicator. Business analyst. Web content manager. Web editor. We are not alone in this regard.

A fellow STC member, during an interview, asked, “In response to the current economic downturn, how do you think your book helps technical communicators weather the storm?” Thing is, unless you know the right keywords to enter into the job listings page, you won’t find the jobs, right? Do you search for “social media” – will that give you a lot of PR and marketing listings? Do you search for “web content” – perhaps, but again, will you find only ad agencies and newspapers using that term? If your specialty is technical writing, producing targeted documentation for a particular audience, what is your role in the web content arena? I think we’re inventing it in the jobs we hold today. Tom Johnson is doing so in the posts he’s writing now, in 2009. Rahel Bailie started the STC Content Strategy special interest group this fall. There are other examples of strategic moves in our field to deliver the right content in the right manner as the web and the social web change the rules, change the contributors, and change us.

But that’s just my viewpoint – what do you see from where you are around the world?


Shopping for a writer on Black Friday?

Boy, do I have ideas for you if your shopping list includes a technical writer, web writer, copywriter, or content strategist. Heck, I have gift ideas for anyone interested in reading, writing, and the web.

Now, you might think the first gift to buy a reader and writer is an ebook reader, but TeleRead cautions against such a purchase on Black Friday in this post, Black Friday: Caveat Emptor. Good to know!

Web Worker Daily has a great post about finding deals on web worker gear on Black Friday. The best idea in the set is to shop for office gear on Black Friday – from printers to monitors to the chair you sit on. Nice!

Portland thumbnail I think that cartography and photography hobbies are quite popular among technical writers that I know. If you’re interested in cool maps as gifts, may I suggest these neat city neighborhood posters at Ork Posters? Under $25, which is a great gift price range. There’s an entire calendar of 31 gift ideas under 31 dollars on

Then there are the Rand McNally fabric maps, waterproof and tearproof, and less than $10. Here’s a link to the Austin, TX one.

I also love the idea of coloring books with intricate designs. Take a look at Designs for Coloring: Prisms and Paisley Designs Coloring Book. Those books are less than $5 each, and paired with a set of fine markers or colored pencils, you’d be giving the gift of doodling.

Travel bugOr how about the gift of technology and hiking or exploring? Geocaching offers the perfect combination of treasure hunting with a GPS unit. You can shop at the official shopping site where they’ll give you ideas for starter kits.

And finally, if you are indeed stumped for gift ideas for the writer you know, query the hive mind by browsing for a while in the gift tag collection, such as “Help me find a t-shirt I’ve only heard described ambiguously!” or “Gift filter: I’m looking for a nifty computer-related gift for a friend’s birthday.

I also have ideas for treating yourself, you poor, overworked, downtrodden writer who loves to read! Have you tried Amazon’s Universal Wish List yet? If not, download it now and start browsing on any website. When you see something you like, click the toolbar button to add the item to your Universal Wish List. Et voila! You select an image, enter the price, and can even put in a description to help people find you (or your non profit organization) the perfect gift. I managed to build quite the mashup wish list – from to to to

Amazon Universal Wish List button

How about you? Are you shopping or wishing this week?

Talkin’ ’bout a revolution at the STC Summit 2010

I don’t know if it’ll sound like a whisper, but I am excited that my proposal was accepted for the 2010 STC Summit in Dallas! Here’s what I’ll be presenting:

I’m participating in a Content Strategy Progression as described on the STC Content Strategy Special Interest Group blog entry on said progression. I’ll talk about content that is “Shareable, Searchable, Sociable, and Don’t Forget Syndicated.” That should be a fun session, and I’m just sad I won’t be able to wander around the room myself and soak in the Content Strategy goodness!

My proposal for a presentation titled, “Strategies for the Social Web for Documentation” was accepted, hurrah. Here’s what I have as learning objectives for the session, but I’d love to hear your questions as well before I prepare all the slidedeck. What would you want to learn?

Session Objectives:

  1. Identify specific types of tools on the social web, such as tags, blogs, and wikis
  2. List risk areas and pitfalls
  3. Identify writers’ roles with social media (instigator or enabler)
  4. Plan a strategy of listening, participating, building and then offering a platform or community

Session Description:
Let’s say that the most driven and driving developer on your team, who also happens to be a popular blogger, comes to you and asks why your end-user documentation doesn’t allow comments or ratings. Rather than stammering something about Wikipedia’s latest scandal, or reaching for imperfect responses that sound like lame excuses, do your homework and learn best practices from others who are implementing social web content that is conversational or based on community goals. Along the way you may realize there are good reasons not to implement a social media strategy, based on studying the potential community and time you’d spend in arbitration with community members on contentious issues, or you may discover that you can borrow from benefits of a single approach while still meeting business goals.

(Kudos if you recognize the song lyrics to which the title and lead refer.)

Trip report from Non Profit Bar Camp Austin

I could only attend Non Profit Bar Camp Austin in the morning, but it was quite enjoyable. Bar Camp is definitely one of those meetings where the conversations had between the sessions can as informative as the actual sessions.

I arrived and signed in and was standing in front of the board right when the orientation ended – and suddenly was surrounded by bar campers looking at the board with me. There was a good variety of topics – updated to add a link to the Flickr photo set with pictures of all the Post-it notes on the board and screenshot of the set.


Austin – experiencing community in the Open City

I decided to first attend a session called “Plug into Austin’s Web/Interactive Scene” with Austinites Steve Golab and Marcus Mateus. They had a presentation talking about the connections we can make in Austin that may not be available in other cities. Austin has a unique vibe, with slogans like “Keep Austin Weird” and events like SXSW Interactive. We support the creative class as described by Richard Florida quite nicely. In Austin it’s cool to be smart, and we are the chosen location for over 6,000 non profits. They’re active in the Bootstrap Austin community. I learned that “Experiences make us happier than possessions” from a CNN article, after they introduced the concept of an Experience Economy. We talked about some of the experience-centered businesses in Austin, from Alamo Drafthouse, a movie theater that serves food and drinks during the flick, to Groovy Lube, an automotive shop with a groovy vibe, After another person’s comment that where you’re sure to be serviced by a hippy-type mechanic at Groovy Lube, about I wondered aloud if the employee experiences is just as important and part of the branding as much as the customer or participants experience. I think Zappo’s is a good example of an employee’s experience mattering as much to the brand as the customer. So, can nonprofits offer experiences? The speakers suggest you could aggregate communities to make a “scene.”

Google Analytics demonstration

For the next session, I ended up offering to demonstrate Google Analytics – someone had put up a Post-it with “Want: Google Analytics Overview” on it for an 11:15 slot, and at 11:14 I decided to volunteer. 🙂 At first it was just me and one other person, but then at least a dozen people joined us. One woman from Settlement Home, was able to demonstrate their Google Analytics implementation. She worked with Trademark Media to get their tracking codes set up. She was able to pull up her Dashboard and show the last month’s worth of visitors and so on. We walked through the various areas of Google Analytics – Visitors, Traffic Sources, Content, and Goals – with stories from many of the participants about what has worked well for them. I especially liked the funnel visualization for tracking the completion of a volunteer application. Our Internet connection was flaky for the first 10-15 minutes, but Chris Boyd, who works at Midas Networks, the ISP for my site, by the way, got us up and running.

One of our discussions was about trying to find out what to measure. One non profit had just started using Google Analytics. With non profits, I believe the goals aren’t always about conversions into sales. The prospects turn into clients or donors or volunteers, instead of customers who make a purchase. So after the session was over, I gathered these thoughts about persona-based goals for websites and tracking.

Personas are profiles of people who connect with your organization. They can be highly detailed, are profiles of imaginary people who mimic real-life people that you know, and are captured in a short report typically. I think that personas would make sense for figuring out the goals you have with web analytics and tracking. Based on looking at Any Baby Can, for example, you may have three personas: donors, volunteers, and clients. They’re going to know way more than I do about their goals, naturally :), but here are some ideas:

Donor persona – some donors want to remain anonymous, is your pathway through your web content giving them that ability? Or if they are the opposite donor type, and want recognition for their contributions, can you track goals on your website that help with that?

Volunteer persona – What are some other goals that a volunteer wants to complete when they come to your website? Do they have a certain day of the week free and want to find opportunities for that day? Did they attend another event and want to find related opportunities?

Client persona – She may be using a public computer, are there particular pathways or goals you can outline and measure? Is the website useful not just for finding information as a potential client, but how is it serving current clients?

These are likely simplistic, but I wanted to share – I had one of those “oh, shoot, I could have described personas” moments after I left bar camp. 🙂

At the very end of the session, I mentioned that I just learned about negative keywords. These are keywords that you use in Adwords campaigns to make sure that your ads don’t show for search queries containing that a certain phrase. That way, people only click through on specific keywords, not related keywords that may not be a good match. A good negative keyword example for Settlement Home (if they started an AdWords Campaign or a pay-per-click campaign), for example, would be “foster dogs” to make sure people looking to foster dogs rather than children not see their ads about foster homes. One non profit was going to apply for an AdWords grant, so hopefully she’ll learn about negative keywords through their strong education program.

Keynote speaker – Holly Ross from NTEN

While I didn’t get to stay for the keynote, the Twitter feed for #npocamp during Holly Ross’s remote keynote was great to follow. One of the more interesting points to me that she made that was tweeted about is that there’s a huge increase (like 600%?) in unstructured data. These are the scattered conversations and communications happening all over the Internet, apparently. How can non profits analyze or monitor unstructured data? Two suggestions came from the person I sat next to in the first session, Gregory Foster: Scout Labs and Radian6.


What a great way to spend a Saturday morning with energetic, positive people making a difference for people especially using technology and communities. A bar camp, with its unstructured format, was a perfect match for this group.

Comparing RSS feeds to social networks

Jakob Nielson and his research group, Nielsen Norman Group, have done it again – letting us know how users are actively perceiving and using social software for different business tasks. This research is important as the social web evolves so that we, as web content creators, know the best ways to present and offer different types of information, especially for corporate sites. He pulls it all together in an Alertbox from October 12, 2009 titled Streams, Walls, and Feeds: Distributing Content Through Social Networks and RSS.

What does this research mean for user assistance delivered through social means?

Voice matters – People wanted a specific voice for certain corporate brands. For example, the BBC was thought that it should have a more professional voice in its messages. But for other corporate brands, people wanted a more casual style, but the biggest reason for unfollowing a company rep on a social networking site was annoyance at the frequency of posting. My thinking? Don’t post your entire release notes links via Twitter in a week – instead spread them out to avoid drowning out the other people that your readers are also interacting with. I talk about finding your voice in chapter 7 of my book, and this research finding is certainly relevant.

Consider context – Updates that came through RSS rather than social networks such as Facebook, LinkedIn, and Twitter, were thought to be more “official” and trustworthy. However, readers have a lot more control over what they see – and readers who read the second page of a stream are nearly unheard of. They don’t seek out past postings. I have seen this happen on my blog here at JustWriteClick – once a post drops off that first page of about 10 posts, it’s only seen again when someone from a search engine looks for something very specific, such as the End-user Documentation in an Agile Environment post. What else is interesting about offering RSS feeds for information is that users’ habits haven’t changed in 3 years, though RSS use is on the rise and people are selective of the feeds they track.

Keep up – Twitter and Facebook are sites that are visited daily – can you keep up if you decide to engage customers there? And is there a place for end-user documentation on these sites? My take is that you shouldn’t start unless you’re willing to keep up. And in many cases, you probably don’t need to start on certain social network sites. If your group haa corporate goals like maintaining customer support by tying the social network interaction very tightly with your end-user documentation, then Twitter or LinkedIn may be a good match. Facebook may be a match also, depending on your message. Non profits, for example, find Facebook a great match for education, training, or raising awareness. If your corporate alignment as a technical writer is with the training and education department, you may find a niche case for using Facebook for promoting learning opportunites.

Make it useful – The most successful messages had substance, were timely, and met users expectations. Message usefulness scored the lowest of all the categories. Yikes. I would hope that as more content strategists and technical communicators apply their skillset to these messages, we can increase the utility.

Write well – Writing specifically for the medium is important to get the results you want. Probably the best way to write well for the medium is to read as much content as you can in the targeted medium. Apparently you can’t just repurpose content or use shortened text snippets that point to a longer one – users won’t click through.

Mobile findings

Only 4% of the users involved in the study sought out corporate messages from a mobile device. What I might infer from that finding is that mobile devices are for necessary in-field information, not for corporate messages syndicated through RSS or posted to social networks.

Email still fits

I found it interesting that email messages and newsletters may still be the best way to maintain customer relationships. Even though the user is responsible for deleting those messages, requiring more “work” than social networking sites, users still don’t browse through multiple messages from corporate “streams.”

Nielson’s summary says it so very succinctly that I can’t help but quote it directly:

Users like the simplicity of messages that pass into oblivion over time, but were frequently frustrated by unscannable writing, overly frequent postings, and their inability to locate companies on social networks.

There’s no crying in Agile!

cryinginbaseballI loved the line, as delivered by Tom Hanks in A League of Their Own, “There’s no crying in baseball!” I know there are times when the crying must happen without delay. I don’t believe most workplaces actively encourage crying – at least not outside of acting careers.

When I’ve read Agile practitioner reports that tell tales of times when technical writers have left meetings and fled to cry, I am not just surprised but a little dismayed.In A Tale of Two Writing Teams from an Agile conference three years ago, one anonymous writing team reported one writer in particular crying during the daily standup and in retrospectives.

As the prioritization changed from the new Java web program (the new and fun stuff) to updating the old, stuffy legacy client server code, writers’ tasks switched from creating new online Help to updating old versions of end-user documentation (books). This change caused the writing team to revert to form—that is, they began to demand written design specs. It’s as if once the technology took a step back from online Help to written documentation because of the prioritization of the product backlog, so did the methodology choice. I tried my best to coach the writers to work creatively with developers on the old stuff as they had on the new, but there was an insistence that the existing specs
for the old legacy code would now become outdated, and the writers were completely uncomfortable with that. One writer—the one with the most tenure—
moved out of the team room, citing lack of privacy and her ability to contribute as the reasons (when I know that it was really a lack of embracing the change). I can remember several episodes of her crying during daily scrum meetings and in

The paper author’s analysis indicates that the stress of embracing change caused the outburst I think the stress of change can bring on an emotional outburst, and sometimes people have crying as their stress release.

But what is more interesting to me as a content provider is that the change in the tools used to deliver the documentation seemed to correlate to the writer’s work habits. As I search for wiki solutions for collaborative authoring on Agile teams, I’m reminded of this article again and again. There’s no crying in Agile, and having an Agile documentation tool should help with change management. Except, of course, the change management associated with bringing in a wiki. Stewart Mader had great suggestions at the recent WebWorks Roundup: make wiki upkeep part of everyone’s job, make it as easy as email, and make it as sociable and enjoyable as riding the train to work each day. Any other ideas? I’d love to hear them.

Consistency and community-generated content

I’ve been collecting examples of wildly inconsistent writing lately. I’m not sure why these have stuck out to me, but when I think of book sprints and community writing events, consistency is an important, though sometimes difficult, goal and outcome.

Why consistency?

You may not be a big fan, especially if you’re a creative type, because you appreciate when something interesting and new pops out at you. Unfortunately, you may be one of the few who appreciates something popping out while they’re trying to learn a task or evaluate a concept or analyze a pending purchase. I don’t believe consistency has to mean “dull” but I do believe consistency gives you expected results both in reading paragraphs and in overall organization.

SkyMall – catalog copy example

For some reason, this bit of catalog copy stopped me in my tracks while I was reading the latest SkyMall, waiting for my plane to take off.
Catalog copy for a watch description:

When you want to raise some eyebrows or have an excellent ice breaker for you next sales meeting, the jaw dropping Gforce MatrixPC is your best resource. The stunning design will tell people that you are someone who is confident, secure, and successful; all traits that will attract the right people into your life. The MatrixPC makes everyone aware that you know what it takes in life.

The last sentence was the most jarring, I suppose. Compared to other catalog copy in the same publication, this one struck me as sloppy, not tight.

Little House on the Prairie – narrative example

I’m re-reading the Little House on the Prairie books as an adult after loving them as a child. This time through, though, I’m amazed at the differences in style and tone and the placement of quite technical descriptions of cheese making, contrasted with stories of children not listening to their parents. I didn’t notice these differences in voice and style as a child, but as a grown-up this roller coaster reading was making me a little nauseous.

Then I learned from this New Yorker article, Wilder Women: The mother and daughter behind the Little House stories that Rose Wilder added much of the “flourish” to the books before they would even be considered for publication. Fascinating. The books still hold together and offer a wonderful viewpoint into American history. But there will always be that reader experience of the feeling some paragraphs are misplaced.

How to achieve consistency with community writing projects

On the FLOSS Manuals site, Adam Hyde writes about tone and style swings in the Book Sprints book, saying:

A book can be frustrating if it switches tone in the middle. One author may write in a jazzy, loose style, such as “Don’t panic–we’ll reveal the wizardry in a minute,” while another might write in a more formal style, saying “The following example is complex, but will be understandable by the time you finish the chapter.” Each style is legitimate and useful, but the reader will feel queasy if the tone makes a big swing from one style to another.

I think that “queasy” feeling is one you want to avoid for your readers.

We’ve worked through this for book sprints with a couple of different techniques to ensure consistency in style, tone, and organization.

One is to hire an off-site editor who reviews and modifies new content nightly during a book sprint. By having that person be off-site, they do not get caught up into the intense group dynamics that happen during the sprint, which is such a focused documentation and working group that they may argue unnecessarily about edits.

Another technique is to start writers out with a simple style guide.On the FLOSS Manuals site, each manual has a link to Agreed conventions for writing this manual. It’s not complicated but it does give writers an idea of what expectations they should meet when writing content.

ottoutlineFor book sprints, we outline ahead of time, using simple Post-it notes or even laying out paper printouts on the floor.

These chapter or topic titles will give writers an idea of what type of chunking of information we’d expect for the manual.

And lastly, lead by example. By providing copy in the style and tone that you expect the entire body of work to follow, other writers are more likely to follow suit.