From the Doc Side : wikis

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.

How do you like your help?

Lindsey Robbins — Mon, 11 Aug 2008 21:00:00 GMT

In the evolution of software help, user assistance content has taken many shapes and forms. The search for the best way to assist you in your every day work processes is an ever changing quest. Long, jargon filled, and confusing technical documentation is hopefully outdated. And hopefully too, the short picture diagrams with confusing instructions. How did we ever figure out how to put furniture together before technical communicators? However, we know that’s not always the case.

Why is it so difficult to make help easy? Well one difficulty is keeping up with how fast software can change but more so it’s about meeting user’s expectations for help in the program. Here are some questions we might struggle with on a daily/monthly/yearly basis –

User Guides -

When you access help, do you want a user guide?
Do you want to see the user guide on the screen side-by-side with the program or do you want to print it out and go page by page?
Do you take notes when you print the manuals?
Do you want a lot of detail or does that take up too much time and paper?
Are you a visual learner? Do we need more or less screen captures?
If we have more, that’s more pages and bigger file sizes.
Do you have the internet bandwidth to download big user guides?
How do we document everything but not overwhelm you with the number of user guides?
Do you learn by area of the program or depending on the process you’re performing?

Help Files -
Or, are you the type of user who doesn’t have the time for printed manuals and you just want your answer now. You want to search through a help file or knowledgebase and get back to doing your work.

If you are this type, how do you search?
Do you want similar information as the user guide or do you want just problem solving information?
Do you need visuals?
Do you need a glossary or index?
How do you want the help to appear in relation to the program?
How do you access the help? Do you want to hit F1 on the keyboard? Need a question mark icon to click? Or do you miss the days of Microsoft Word when that paper clip would pop up trying to guess when you needed help?

General Documentation Questions -
Then there is the multitude of other questions we might ask ourselves:

Do you want other user’s advice on what works or doesn’t work? Kinda like user reviews on store websites.
Do you want to be able to edit the content yourself?
Add a comment?
Do you want to save the documentation so you don’t have to remember it?
Do we need more web 2.0 types of content and how would we manage it?
And even more so, how can we marry the help files, user guides with other efforts in the company like knowledgebase, training, and support?

These are a few questions jumping off the top of my head. If I quizzed other team members, I’m sure this post would become exponentially longer. We do know from our documentation survey you still prefer having user guides. But we then have to manage how your expectations might change now and in the future. If we don’t start preparing now we won’t be ready then.

This topic really struck a note with me recently because a well respected technical communicator in the field decided to publish content for her users in the form of a wiki and stop creating manuals.

I’m interested in seeing how this goes. I’m aware that her audience needs might be radically different than ours but when you’re focused on day-to-day tasks it can be hard to remember to look out and see how our field is trending. I’m not sure what our users will ask of us in the years to come. It’s exciting and I know whatever you expect of us, we’ll do our best to deliver top quality.

Have any opinions?

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!