Monthly Archives: January 2010

Email feedback mechanisms for online help

Email has become a universal conversation mechanism for business to business notification, customer to business communication, you name it. If you’re not doing so already, you can add email links so that readers can send emailed feedback to your technical documentation team. With advanced mailto markup you can automatically enter a subject line, indicate who the email will go to, as well as enter courtesy copies and blind courtesy copies to additional people. Your inbox should not be overwhelmed with feedback emails, but a link should give customers the feeling that their comments are collected and concerns addressed. This is conversational documentation at its simplest.

If you have a large helpsite, you may want to know where the click occurred. You can use Javascript to get the URL of the page or the title of the page and automatically embed that into the email that is sent. Here is sample Javascript code to put into either the top of each HTML file or in a separate file that the HTML file refers to. You can see this code in use at, thanks to Melissa Burpo‘s implementation (she adapted code from for us).

<script language=”Javascript” type=”text/javascript”>
var subject = “Help feedback: ” +  document.title
var bodytext = “Topic: ” + document.URL + ” – ” + document.lastModified
var pagesubject = “Link to topic: ” +  document.title
var pagebodytext = “Topic: ” + document.URL

//output an email link
document.write(‘ | <a href=\”’ + pagesubject + ‘&body=’ + pagebodytext + ‘\” title=\”Email this page\”>’);
document.write(‘Email us</a> |’);

Some of the benefits of this approach is that email is simple and universally understood by customers. An email link offers a feedback mechanism without much overhead programming or implementation. But you may need to watch out for email collection robots that take your email addresses from the mailto code and use it for spam purposes. Also, you might not get the type of feedback you want, such as people only reporting typos, rather than offering substantial additional information.

I’ve got an article that will be published on the WritersUA site soon with additional conversation and community documentation examples, but this one is a great starting point if you have your help site on the Internet but haven’t started interaction with customers at all.

Collaboration thoughts

Some of my favorite quotes that make me chuckle are the ones about collaborative authoring and the difficulty being people, not tools.

For example, Alan Porter recently wrote an article Wikis in the workplace: a practical introduction for Ars Technica. My favorite line from the comments was “Remember that the people contributing to it are the same people who steal each other’s lunch from the fridge and regularly screw up the different between reply/reply all/forward.” Bwah hah ha.

But intense collaboration efforts can be inspirational. For example, Adam Hyde, the founder of FLOSS Manuals, recently tried out the new collaborative authoring platform, an open source product called Booki. Last week they held a book sprint at Transmediale festival ( He was quite nervous about it – not only were they trying out a new collaborative authoring tool, but he also had not led a book sprint for a book that was not an instruction manual.

With five authors to start, and post-it notes galore, the team outlined the basic concepts and ideas they wanted to explore in the book. The Collaborative Futures book writting in five days is now available at With 33,000 words and a 200-500 copy first run, by traditional standards it’s a success, or as Mushon Zer-Aviv puts it, “It is not bad at all”.

I’m finding the blog entries that chronicle the event are as interesting as the book itself. Obsession about attribution, a healthy disdain for Web 2.0, anonymity, and collaborative economies, you’ll find it all in the book. The writers wrote from 10 AM to midnight four days in a row. Any writer can respect that level of effort.

One interesting story comes from one of the participants, “Collaborative Futures Day2: “Knock, knock.” “Who’s there?”

Around noon today we hear a knock on the door. Now let me just explain the set up, we’re working from a hotel room in a complex called IMA Design Village, on the 5th floor of an old (nicely) reappropriated industrial building with a jerky elevator and nothing to really point you at where we are. All of us were in the room at the time and we were not expecting any company. We opened the door and there stood a guy around our age who said he has heard about the project and he wants to contribute.

We were both amazed and mainly unprepared. He didn’t even say his name, he just said he had some ideas about collaboration and he really wanted to contribute. That was just completely great! But while we announced that the collaboration will be later opened to remote collaboration, at that moment, in that place we were completely unready for more people in the room. Adam (which the mysterious contributor said he met in some obscure music event in the city) have went with user-X downstairs to the cafe to discuss the contribution and he (still don’t know his name) will join us tomorrow writing a chapter for the book.

I didn’t hear which chapter the knock at the door wrote, but barriers to collaboration are lower all the time. Michael Mandiberg states a great summary for the sprint, “We spent most of our time talking about about trust, openness, fairness, attribution, respect, organization, and goals. This was a collaboration that had all of these principles, plus it had great collaborators. It was an incredible success.” Sincere congratulations to all the participants!

Last sprint, first step

This week I’m finishing up an Agile sprint. Not just any sprint, though, my last sprint as a technical writer embedded on a sprint team at ASI. I’ve learned so much there in the last couple of years that I’ve decided to make a go at consulting. I want to help people with content strategy, social media, and any tools they need along the way such as collaborative authoring, wikis, web content management systems, or DITA.

This week is my last Agile sprint for a while, but I think I’ll adopt some Agile principles and apply them to my new work lifestyle as an advisor for LugIron and a contractor for Informatica here in Austin.

  1. Only deliver things that an actual customer would find useful.
  2. Deliver something that I consider to be done, shippable, and customer- ready.
  3. You can do any task, no matter how daunting, if you slice it thin enough.
  4. You should list and prioritize all tasks, large and small, that get you incrementally closer to your goals.
  5. Create prototypes all the time, no matter how rough or simplistic. Keep polishing as you go.
  6. Reflect periodically, and change what’s not working well.
  7. Understand the business goals. Clarify when needed by asking questions and seeking the details.
  8. Welcome changing expectations and requirements. Embrace change.
  9. Maintain a sustainable pace. I should be able to maintain a constant pace forever.
  10. And if all else fails, don’t overthink it, and go get a beer.

Pilot or not?

While doing some research for LugIron, a startup here in Austin where I serve in an advisory role, I found a slideshow discussing signs of successful community launches by Joe Cothrel, a VP of service at Lithium.

Now, what they mean by “community” is a larger than 5,000 person audience, enterprise-type (B2B or B2C focused communities), and containing primarily forums and blogs (followed by everything else.) So, it’s not quite the same as the wiki communities that I’ve studied and participated in. But, what’s interesting to me is that one of his Warning signs on page 8 is a quote from the enterprise:

“We want to do a pilot.”

Huh? Really? Wanting to do a pilot is a warning sign of eminent failure? I guess with blogs and forums, you would want full dedication to the efforts and the goals of the community. But with wiki communities, I think a pilot is a great idea. Pilot content, pilot collaborators, pilot wiki.

What do you think? Do wikis fold up easier than forums? Are pilots getting a bad name in corporate-sponsored communities? Is this a case of the vendor wanting full dedication in their sales engagements?

techpubs tools work writing

Clearing the Air on Cloud

One of my readers asked for a post about cloud computing. I went straight to my in-Austin expert, Ynema Mangum, and she exceeded my expectations by writing the post! This is a guest post by Ynema Mangum, architect at Hewlett-Packard. She contributed information about web metrics to my book, Conversation and Community: The Social Web for Documentation. She’s working on a chapter for the upcoming book Cloud Computing: Principles and Paradigms. I’ll post a second guest post from Ynema next week.

Cloud computing represents a paradigm shift from traditional IT rooted in heavy process and technology-centric management to agile processes and service-centric management. This shift converges with Web 2.0 and distributed application design, resulting in democratized computing and an economic revolution — where the developer can deploy enterprise grade applications and user services without having to pay the capital expense for the underlying IT infrastructure. It represents a radical change and requires a culture shift for IT when building a private cloud.

Today, confusion exists about exactly what cloud is as well as how it compares to current IT methods and technologies. Clearing the air is the first order of business.

Public Cloud vs. Private Cloud

The public cloud model has is vastly different from the private cloud, creating a chasm in their connection. The current expectation for public cloud infrastructure and platform services is the ability to provision compute, storage, database and networking resources in a few minutes, completely online without establishing an agreement or talking to a person.

Private cloud computing has different challenges for the service provider, but often is faced with the same expectations. Regulatory compliance, security, and privacy are just the icing on the cake. The concern that seems most often forgotten in comparing public and private cloud models is quality and compliance of data.

Public cloud providers, in general, do not care what type of application or data you throw on the cloud. Compare that with an enterprise private cloud, where IT not only owns the performance and availability of the organizational assets, but also has responsibility for ensuring that business assets are used in the proper manner. Applications that are developed and deployed on a private cloud need to go through a series of quick checks before they can be cleared in order to prevent misuse of company assets or the risk of retrofit and ground-up redesign of applications developed outside of IT.

There is an ongoing challenge in enterprises today to segment cloud service offerings, architectures and buyer types into useful, focused categories for strategic planning, according to Frank Gillett of Forrester. For public cloud service providers, two IaaS market categories have emerged, the software Platform as a Service (PaaS) and virtual Infrastructure as a Service (IaaS) offerings that differ by level of infrastructure service and abstraction offered.

For private clouds, there are two types of compute clouds, server clouds and scale-out clouds.

  • Server clouds are built for the traditional needs of the business applications, catalyzed by x86 server virtualization and adding self service provisioning.
  • Scale-out clouds are designed for massive, highly distributed applications.

Virtualization vs. Cloud

Virtualization and cloud computing have much in common, including phrase overuse and hype, resulting in a lack of understanding of both. Cloud computing does not equal virtualization, but does use abstraction as a common element in each layer of the cloud. In fact, the most distinct differences between the two terms seem to be in the areas of abstraction and IT maturity.

Virtualization is datacenter-centric and technology-centric, while cloud computing is service and user-centric. Memory, desktops, applications, storage, applications, platforms, and servers can be virtualized, or abstracted from the underlying technology. Cloud computing can use or not use virtualization in its architecture.

Typically, the virtualization referred to for use in cloud computing is operating-system virtualization, where multiple virtualized machines can run on a physical server, secure and isolated from one another. These VMs provide benefits in that they can be provisioned without requesting physical hardware, changed, moved, controlled, terminated, and configured more easily than a physical machine. This results in greater efficiencies and productivity in IT, and also increases agility for the services developed and deployed on these VMs.

Beyond this layer of virtualization, cloud computing adds platforms, agile processes, and services for developers, providing value far beyond virtualization.

Utility Computing vs. Cloud

Utility computing is a business or economic model, whereas cloud computing is about technology and process architecture. Utility computing allows users to receive computing resources and “pay by consumption”. Cloud computing is a much broader concept, taking into consideration the underlying architecture and actual services delivered.

Consumer users have been reaping the benefits of the utility model in cloud computing for years — at the application as a service level. It is developers and IT who are using cloud computing in a transformative way now. IaaS and PaaS allows them to develop, test, deploy and run apps that can scale on enterprise grade technology, all without having to pay the capital expense for the underlying infrastructure. This is creating a new cloud economy and truly represents the democratization of computing.

Context and behavior

I appreciated SocialText’s Ross Mayfield describing the various levels of interaction in his One on One interview with Fierce Content Management. The interview reminds me that social context alters behavior and motivations. Think of an intranet situation, where interactions are between bosses, colleagues, direct reports, and coworkers. The goals in this context are to increase productivity and collaboration speed, but corporate culture changes motivations. Then consider the context of an internet site, where interactions and customer relationships can be deepened and enhanced while providing customer service. Contributors to a wiki or any online content management system will certainly vary their behavior in accordance with the offline expectations of them.

I think it was in the book Groundswell that I read a case study where a company brought in a wiki, thinking that Generation Y employees would embrace it. But Generation Y wisely stayed away, because they didn’t have the authority required to make the system work well. Since the higher-ups stayed away from the new system, there was no leading by example, nor was there incentive for the newest, less tenured employees to use the system.

Patrick Davison is a digital artist living in NYC, and he designed the cover for my book. His Ignite talk has a similar theme – considering how your reasons for using a particular site or application (such as Second Life) shapes how you act there. The title is “The Plight of the Digital Chickens” and I think you’ll enjoy it as much as I do.

What are other examples of context shaping online behavior? I’m sure danah boyd has great examples in her papers.

New year, new look

If you’re visiting the site rather than reading this post through a feed reader, you’ll notice some changes to the look of the site. I’m using the Excellence theme from BlogOhBlog with some tweaking. While the theme enables ads, I’ve decided not to offer ads on my site. In place of the ad images, I’m using some excellent hand-drawn icons for links to my profiles on various social sites.

My new profile photo was taken last fall by the same photographer who took my last set of profile photos, Beverly Demafiles Schulze. She has a great eye for interesting backgrounds, and we wandered around The Domain in Austin on a nice sunny day in Austin.

I’d love your feedback, especially on the “Read more” links to get the whole post and the comments.