From the Doc Side : emerging technology

User-Generated Help: Future of Documentation?

Lindsey Robbins — Wed, 26 Nov 2008 18:07:00 GMT

Of late, I’ve been intrigued by something YouTube is doing. They are requesting user-submitted documentation in the form of videos. Well the video part makes sense, right? However, it’s interesting they are reaching out to the audience to supplement their official documentation. Is it fair to put the burden on the users? Fun for users to participate in developing help?

They are now doing a second round of submissions. You can read about it in their blog. And, you can review the round one selections.

One interesting thing, they didn’t ask for just any help submission, they provided a list of topics to choose from. If your video is selected, it is then posted side-by-side with their content. And, they claim their help gets 1 million + users a day. Not sure if I believe that or not but it’s still interesting (I've never clicked on the their help but maybe I'm an anomaly).

This is definitely a topic I’ll keep my eye on as help and documentation might be figuring out how to join the web 2.0 world. But then the question still remains, when do you ask for user-generated help? I mean, it might be a pure guess on my part but I don't see a million people rushing to create help content. Most people would rather visit the dentist then spend time explaining things to others. Unless you're like me. And if you are, welcome to my ~~crazy~~ cool world.

Have a Helpful Idea?

Lindsey Robbins — Thu, 20 Nov 2008 18:56:00 GMT

Your suggestions are heard. Yes, I know it can be hard to believe sometimes but some people (finger pointing at me and the rest of Blackbaud) love to listen. Listening is fun because you don’t have to pretend to know everything. You can let others share their unique experiences, thoughts, and visions with you. And then as Shaun Sullivan said, steal it as your own genius idea. Okay, I don’t think I really have the guts to claim credit from anyone (and I'm pretty sure he was joking) but I do dig hearing other people’s ideas and researching them further.

In fact, a bunch of our technical writers were sitting in Shaun’s Emerging Technology session at Blackbaud’s Conference for Nonprofits this past Monday and listening. He was discussing how you can search the Infinity apps and how it intelligently provides results including an index of our help. And a great question was asked… Can you pull in a 3rd party help to be indexed as well?

Hmmm… good idea!

As our senior technical writer said in the session, we’ll look into it. And let me say, I’m pretty sure we’ll have some great discussions and research about it. Either way, I want to acknowledge that the question was great!

So what’s the point?

I just wanted the opportunity to say we’d love for you to share any other ideas you have. None are bad. All ideas, even in the most basic form, can be sparks for improvement, conversations, and even other ideas. To submit a good idea, leave a comment on the post (login or register for free in the upper right corner) or email us anytime at documentationcomments@blackbaud.com.

Journey from Structred Frame to SharePoint Server Wiki

Lindsey Robbins — Tue, 18 Nov 2008 11:36:00 GMT

The journey from last week to this week already feels a decade long as I’ve encountered many trials and errors in converting internal team documentation authored in Structured FrameMaker into a Microsoft SharePoint Server 2007 friendly format. In other words, complex framemaker to basic html.

I’m not complaining about the trials and errors. On the contrary, it’s been exciting to dig my hands into this fun little side project that keeps evolving and building.

Well really, I need to take you back three years to get to the root of where I’m at now. It all started with two separate projects. The first started as learning about how we generate help from Adobe FrameMaker using WebWorks and my lesson was our internal documentation help file the Tech Writer Master. Sounds intimidating doesn’t it? I spent a lot of time updating, organizing, and examining the information design of the help file. Unfortunately, a problem we frequently faced was there wasn’t an easy way to quickly and efficiently update the internal documentation. And as you know, processes, workflows, and general daily work information is fluid and changes often. So I kept the internal documentation as an interest especially because of my passion for knowledge management.

Then that summer, I was tasked along with another co-worker to research how we might, and whether it was valuable, implement our help file as a wiki. We ended up going a different direction with our Infinity help but I was able to bring in my wiki experience and often ask myself what role wikis could have in user assistance content. When the wiki project ran its course, I kept up with the free wiki tools out there and wanted to find a way to install on my own machine and run as a web server for my team. I knew ultimately that having the Documentation team work on a wiki would provide valuable experience in new ways of thinking about content management.

Months went by and my company rolled out Microsoft SharePoint Server 2007 as our internal company content management system. I knew SharePoint had some wiki capabilities but I had to test it and see if it could work for us. I ended up choosing a Wiki Site from their templates. I played with it and in a matter of days, I had a team wiki set up. It wasn’t perfect, didn’t have all the features I wanted (especially around navigation), and proved frustrating at times but I was able to get the basics of what I needed up and going. And once it was set up, I presented it to my manager who pushed me to present it to the team.

So now, a few months after my team presentation, my little baby project is growing and providing new challenges. Our team is in the process of implementing it and that means gathering content from everywhere it’s been spread out and organizing it on the wiki. Which brings me to the conversion of docs from FrameMaker to HTML.

I tried a couple different methods before deciding on a winner -

FrameMaker to PDF. From PDF, save file as html. Issue: Formatting errors especially concerning images. Would involve too much cleanup.
FrameMaker, save as XML. XML to HTML using an XSL stylesheet. Issue: Worked sorta, but it would take a long time to convert and would need to spend some time creating a style sheet that fit our wiki needs.
Winner: I ended up using a basic WebWorks dynamic html template to generate one html file per FrameMaker chapter. I quickly chose the mapping for the Source to WebWorks style but after a few times choosing the styles, I quickly figured out what I wanted for the output. In some cases, I was able to eliminate some formatting later on by choosing not to output certain Frame items. I still had to do some cleanup but mainly that was around cross-references and updating the file paths to the images.

While there is still some manual cleanup in generating the html files, I am glad to have a pretty easy process to get our current documentation into the wiki. And, I even have a new member of my team helping with the setup of the wiki. Between him and I, we’re going to get our team’s content up, properly formatted, and perhaps even some consistency in the style of the content.

My hope, start 2009 with our knowledge management system in place and ready to be updated in real time. To say I’m excited is an understatement. It’s pretty cool to turn an idea into a reality.

Very delicious or dangerous?

Lindsey Robbins — Tue, 10 Jun 2008 20:01:00 GMT

Being involved in information on a daily basis and trying to keep everything organized in my head I'm always looking for tools to streamline and simplify the process. An online tool that's been on my periphery of late is del.icio.us. del.icio.us is a social bookmarking site. It has a bunch of neat features and yet there is still a lot for me to learn beyond the surface. Here is what I've learned…

Your bookmarks are saved online no matter where you go.
You can share your bookmarks with others or keep them private.
You can network with others in your field or on your team to share your favorite websites, blogs, articles, news, etc.
Do you hate how you search for something but the website creators described it in a way you would never think of? Well del.icio.us takes that away from the powers that be and gives the power to the people. It's a concept called folksonomies. We decide how to describe a site, tag it, and share it. Over time, the more people bookmark something the easier it is for you to find.
You can see your tags in a list, in a cloud, alphabetically, most recent, how often used, or in bundles. However your mind organizes things, del.icio.us can probably accommodate.
Have you gotten to the point where you love google but can't stand the eight billion, five million, and two results that appear. How do you pick which link is the golden ticket? If you're me, you do a lot of clicking and navigating back to the search results. The nice thing about del.icio.us is that it improves google. How?
- Use your network to see what they are reading.
- Because information is organized by how users tag them, you can search based on your word and know you're getting information that's more accurate.
- Save your research on del.icio.us with your comments appended. Other people do the same and you can read their comments. You get an instant evaluation before you even think about spending time searching a website for your research.
If you have some really nice friends, they might even save a link just for you. I can see how that would be awesome on my team. We use email but how easy would it be to lose track of the email?
Subscribe to your favorite tags. If something new appears with that tag, it aggregates itself all nicely for you on your subscriptions page. No more searching for info, sit back and wait for it to come to you.
Post manually or install a plugin for firefox and a button for IE. If you install the plug-in, bookmarking a page is as easy as clicking a button on your browser whenever you are on that really cool website.
Here's a plus that probably only a technical communicator can love, the site has easy to understand help written in an easy to read style.
Are you using Facebook to social network with your constituents, colleagues, peers, etc? del.icio.us integrates with Facebook! Can you feel the synergy?
Does your organization have a wishlist of items? Create a wishlist of items you need, append with comments (like how many, sizes, numbers, etc) and share that with your constituents. If you're like me, it'd be a list of cool things like a wii, a Barnes & Noble gift card, a road bicycle, nike workout clothes, and an iphone that would magically be shared with my family and friends in approximately five months ;-).
Collaborate with your colleagues, co-workers, constituents, donors, volunteers etc to raise the collective knowledge of a group. This could especially be useful if it has bookmarks to news, calls to action, important resources, and more. Just imagine your network helping your organization be better. That might be in the long range plan but in the meantime...

The only part I have yet to figure out is how not to get overwhelmed by all the wonderfully organized and abundant information. I love information but in this context it's almost as if I could get lost in learning. Is that a bad thing? Is social bookmarking too much of a good thing?

The Business Case for Twitter

Lindsey Robbins — Thu, 05 Jun 2008 22:39:00 GMT

Lately, much has been said about Twitter. Chad wrote a great post (Twitter Makes Relationships Work - Right Now) with an explanation of what Twitter is so I'll skip the overview and get to the business case.

Let's start with a little confession I should make… For a while, I had a twitter account but didn't use it much. I wasn't quite ready to be a twitter evangelist. Everything changed for me when I chose a focus for how I was going to use twitter. What I realized was while I didn't always like the concept of letting people know all the mundane things I was doing in my average day, I did like how it could improve my professional and business connections. Here are some ways to use twitter in the business/professional sense.

1. Follow your colleagues. Not only do you create connections across teams but you can stay informed of the latest news in their world. I am following a few leaders in my company with specialties in technology, webby things, marketing, customer support, etc.
2. Follow fellow professionals. This is perhaps my favorite way to connect. I love learning about what other people in my field are learning, doing, finding. I could never keep up with all the changes in technical communication and I don't have to. Instead I can look to peers and mentors for what they find interesting. I share the things I find interesting and our worlds really do expand.
3. Promotion! Share your work content. I am posting a link to our From the Docs Side... blog every time I write one. If we do something else cool, I'll share that too.
4. Tweme the possibilities. If you don't know what a tweme is, it's adding a hash mark to posts so they can easily be found in public streams. I had such a good time at my recent technical communication conference by tweming with other conference goers. Here's our example. Just by putting in a hash mark we could follow each other's post on the same topic. There are so many possibilities with twemes. You could create one for your local professional chapter, a conference, topics in your organization you want to separate, etc.
5. Tweetscan. Tweetscanning is searching all twitter streams for specific keywords. You want to know about technical communication, type that into tweetscan.com and you can find what other people are saying about tech comm and perhaps you'll find some cool new people in your field to follow.
6. Want to know who's the most popular in twitter, go to a site like tweeterboard.com. This site ranks people on popularity. This is again, another way to find noteworthy people tweeting.
7. Support social causes. Movements are happening on Twitter. Just google Frozen Pea Fridays or read here and you can learn how they started a movement to support a woman with breast cancer and ultimately raised money for research.

Either way, definitely re-consider your use of Twitter. You get to control who's in your network and who you want to follow. Also, if you type twitter apps into google, you'll discover new apps are being created daily as people are learning to harness the power of micro-blogging. After all, not everyone has the patience or time to read long blogs like this one. Instead, we want quick updates under 140 characters in length.

Even these guys are tweeting and they're no slouches -

Guy Kawasaki - http://twitter.com/guykawasaki
Robert Scoble - http://twitter.com/Scobleizer
Kevin Rose - http://twitter.com/kevinrose

So, are you ready for the twitter movement?

Wikis Need Some Love (and best practices)

Lindsey Robbins — Wed, 28 May 2008 14:47:00 GMT

Since June of 2006 I’ve been moderating wikis as a part-time job for a company in Seattle. And then soon after at Blackbaud, we’ve explored and researched the use of a wiki as a help file. Since then, I’ve been focusing my efforts on creating an internal documentation wiki as a team development tool. Through my experiences, I’ve learned a few things about how to encourage best practices in wiki use.

Before you implement a wiki, spend time populating it with common topics and a basic set of information. Don’t just hand out a blank one to your team and expect them to figure out what to do with it. By establishing content already in the wiki, people are more comfortable following an example.
Before and during implementation, you need to spend time on the organization. Pages will be added, moved, and deleted. You need to keep the pages organized so that users don’t freak out when they see a mess of pages. People like boundaries, rules, organization – it provides a comfortable structure for them to contribute towards.
People need prompts and templates. Thinking about style and creating easy to use templates always encourages people to contribute more. But don’t expect them to use these things perfectly, clean up will need to be done. And prompts are always good to help guide people towards the behavior you want them to exhibit.
Be an active member yourself. People like strong leadership in a wiki especially where so few will become active participants.
Don’t underestimate providing multiple modes of navigation. Search, most recently updated pages tool, traditional table of contents hierarchy, and tag clouds are just some examples. I’ve also had a lot of success changing up links on the main page to continually bring new content and pages to users’ attention.
Peer to Peer messaging works. People can easily forget what they were doing two minutes ago so I don’t expect them to think of the wiki all the time. Instead, it’s extremely helpful to send P2P messages to users with a combination of prompts and links.
Users really like recognition, polls, and comments. If you can include these three things, you’ll be doing well. Recognition for contributions may be only a pat on the back but it means a lot to community members. Polls are great for opinions and everyone has one. And comments, well that’s a way for community members to connect, ask questions, and in general feel safe from the pressure of actually editing a page. Chances are if you can get them commenting, you’ll eventually get them editing.
WYSIWYG is a given. But going above that, see if you can provide a way to make adding pictures, video, widgets, and more easier. This will not only make the wiki more dynamic but people aren’t always lovers of long pages of static text.
If pages are getting longer and scrolling gives you hand cramps, do your wiki users a favor and break up the content into sub-pages. You can then use the main page as a starting point and create links. Wikis aren’t meant to be books or just content storage. It’s interactive, ever evolving, and (shockingly) fun!
Don’t underestimate the importance of a good moderator/editor. Life in wiki land can easily get out of control if you don’t have someone watching, loving, and caring for your wiki. Or, it can get all dusty and desert like if no one provides some attention to growth whether it’s encouraging participation, providing opportunities to contribute, or keeping pages clean and organized. It will also help if this moderator/editor is an expert in the wiki topics because then they can verify the content as they supervise it. As we all know, wikis can bring the best out of our collective knowledge or the worst and when it comes to work wikis, we all want the best.

Those are just my top ten tips for wiki use but I’ll continue to post on wikis if anything new develops, if you seem excited about wikis, or if I learn something geeky cool that I just have to share with y’all.

And please, if you have questions about my experiences or if you have a problem and want to troubleshoot, just send me an email or add a comment below. I definitely would love to share my passion for wikis with others. I don’t know why it is, but something about community created content gets me all tingly inside.

Where's the download button?

Lindsey Robbins — Thu, 22 May 2008 13:15:00 GMT

Google posted on their blog today that Google Sites is now open to everyone. Curious as I am, I checked out what this new Google Sites feature was. After all, I knew they had acquired Jotspot a while back and now we get to see how they reconfigured it.

It appears to be a combination website/wiki creator. You can control who can edit the pages, view content, etc without having to know html. I love WYSIWYG more than I probably should but even that love will probably not make me an earlier adopter of this option for professional reasons.

The one major flaw in all these websites that make creating websites and wikis customizable and personal is the inherent flaw that instead of you controlling access to the information by having it on your own network, they are all hosted online. And if by some chance there is an option to host it yourself on your own network, well that’s where the fees kick in.

Even though this is a particularly sensitive issue for someone like me who works for a public company, I think it’s an important issue for every organization – private or nonprofit – to consider. I love the value of having software hosted but only if it’s done within the scope of a contract and ensuring your data is protected like we do here.

However, as massive as Google is and as smart as they have been with their apps in the past, I still don’t trust keeping our information on a hosted website. Too vulnerable.

This is something I’ll continue to follow because I have this ongoing dream to have an internal documentation wiki for the Documentation team. We have a lot of information that needs to be managed in order to successfully share with each other and pass on to future technical writers. I’ve been downloading and testing as many free apps as I can find with no luck yet. You need to have more programming knowledge than I have to install. I really think if they can make hosted versions online easy for consumers, why can’t they make installable versions easy too?

In the meantime, I guess it’s back to figuring out the good and the bad about Microsoft’s SharePoint wiki features. Yikes!

Integrating Emerging Technologies on a Daily Basis with Existing Work Processes

Lindsey Robbins — Thu, 15 May 2008 21:46:00 GMT

Something that’s been on my mind a lot lately is the role of emerging technology and how to incorporate it into the documentation process. I’ve known about some of these emerging technologies for a long time but lately I’ve been thinking more about how we would actually go about implementing them on a daily basis. We all want to reach our users in the best possible medium with the most effective means. I especially feel that way about our team at Blackbaud. As a team, we’re always talking and trying to improve our processes and products (for example, see the post on our survey).

For example, I’ve been thinking about these emerging technologies…

Blogs (how we’re going to best use our From the Doc Side blog)
Wikis
Client contact databases
Latest usability trends (including how to best use results from our survey)
Adobe’s Technical Communication Suite
XML and Structured Authoring
DITA
Twitter, Facebook, and all other social networking ways to connect with other professionals and users
User feedback in help files
Short video demonstrations in PDFs (Adobe Captivate flash videos)
3D PDFs (see this example from Adobe)
SEO (search engine optimization)
iPhones and the trend towards mobile phone Internet use
and the list goes on…

However, whenever my brain feels like it’s about to explode, this “but…” appears. It’s this reminder to myself that no matter how cool you become with emerging technologies you still have to do the basics well. I could write a piece of documentation and find this cool new way to make it easily accessible right when you need it most but if I don’t write the explanation very well in the first place, how helpful am I really being to you?

So no matter how much I like to learn and understand all the newest technologies and tools appearing out of nowhere on a constant basis, I want to make sure I’m still doing my basic tasks to the best of my ability.

And, along with doing the basics well, I have to remember that just because we have the power or the ability to do something amazing doesn’t make it the right decision. Just maybe, if people are asking you for a splash pool in the backyard they may not be quite ready for the ocean. Sometimes the simple solution really is the right one even if it’s not the most cutting edge.

Perhaps the answer to my solution to incorporating emerging technologies is to introduce these exciting developments in manageable small chunks and evaluate their effectiveness in an ongoing basis. I don’t want to overwhelm my users and myself when it’s possible for us to get there just not right now.

As you can see, I’m still learning this concept called patience because if I could, I would change into a superhero and improve your world in a day. I know you’re the same way too. So since we’re not getting fitted for red capes anytime soon, let’s work together on this process and see how we can do the basics well. I think if we spend time on the quality and really listen, we can incorporate emerging technologies on a realistic timeframe that’s comfortable for everyone.

What do you think? Have you put any thought to how you're going to integrate emerging technologies into your work processes?