From the Doc Side : PDF

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.

Extra!! Extra!! Read All About It!!

Betsy Unger — Mon, 04 Aug 2008 19:38:00 GMT

BBNC 5.5 USER GUIDES POSTED!!

Greetings! With the BBNC 5.5 release, the documentation team is proud to announce that a new set of BBNC user guides has been released! New user guides include the Website Design Guide, Team Fundraising Guide, and the User Networking Guide. In addition, we posted a FAQ for your fundraiser team captains. The FAQ includes details about how to use the participant dashboard. We recommend you save the pdf and email it to your team captains.

To manage the list of guides, we updated the BBNC user guide page on our website. Now, after you click Blackbaud NetCommunity on the User Guides page, a BBNC “flavor” page appears. What BBNC flavor do you need? That depends on the Blackbaud product you integrate with BBNC. The four options are BBNC for RE, BBNC for BBEC, OCC for EE, and OCC for SIS (if that is not enough acronyms for you, I can go on…).

After you click the BBNC “flavor”, the entire set of user guides appear for that version of BBNC.

The list of user guides is listed below. For a guide that appears on each page, such as the Website Design Guide, the user guide is specific to the version you need. To clarify, the Website Design Guide that appears on the BBEC for RE page does not contain help content for OCC parts. OCC information is specific to the user guide pages EE or SIS.

Blackbaud NetCommunity Configuration Overview
Blackbaud NetCommunity Installation Guide
Program Basics Guide
Website Design Guide
Email Guide
Administration Guide
Chapter Management Guide
Team Fundraising Guide
Team Fundraiser Dashboard FAQ
Personal Page Management Guide
User Networking Guide
Blackbaud NetCommunity & The Raiser’s Edge Integration Guide
Blackbaud NetCommunity & Blackbaud Enterprise Integration Guide
NetConnection Installation Guide
Online Campus Community Update and New Features Guide
Online Campus Community &The Education Edge Integration Guide
Online Campus Community & Blackbaud Student Information System Integration Guide

Enjoy!! We hope you love what you see. These user guides are now broken out by topics and better organized. For you, our hope is this provides a way for you find the BBNC help content you need faster and successfully.

So, who needs a BB acronym test….?

Doing More with Adobe Acrobat and PDFs

Lindsey Robbins — Tue, 22 Jul 2008 15:55:00 GMT

I love research. I love it so much I research what we could be doing five years from now. I like to know things. Being prepared for upcoming changes is an understatement for me. When I went to the STC conference in June, I saw a demo of Acrobat 9. Wow, it did some slick things. However, it meant it was time to go back to the ~~drawing~~ research board. We've heard of some issues with the Technical Communication Suite that Adobe is promoting with Acrobat 9, so we aren't sure when we plan to upgrade. However, when you're researching five years out you don't worry about small details (I mean, who worries about broken software, lost files, and loss of productivity migraines?). However, this line of thought did produce some questions about what we can do with Acrobat now and what we might want to consider doing this next year, two years down the road, and five+ years down the road.

On the Documentation team, we use Adobe Acrobat as part of the process to create our user guides. Among the things we already provide in our user guides include - bookmarks, table of contents, index, cross reference links, space to make notes in the margins, and more.

A new feature we're testing on the Education Edge, Student Information System, and Financial Edge 7.77 products is a new bookmark - Search the guide. We thought we'd try to make the process to search through a PDF for your content easier. When you click Search the guide, Adobe's search feature opens and you can enter your terms. The PDF search function is pretty good and I use it often when I try to locate existing content. Instead of relying on users to know where in Acrobat to go to for the search feature, we've added the bookmark so it's visibly present when they open the PDF the first time. Simple change but yet we're hoping it improves the usability of the user guide.

For longer term research, I've been hearing about other ways to increase the functionality of the PDF. Recently I received an email about enabling PDFs for comments. In short, this feature would enable users to make comments or notes in the documentation as they use it (very web 2.0 like). I like that it takes information (user guides) our users have already said they like (in our survey) and expand its usefulness. An article from Shlomo Perets discusses some ways to enable PDF comments. For us, it would require an update to our Adobe products and with our issues in the Tech Comm Suite it's not a good decision for us to implement. While we wait for Adobe to sort out its business, I am going to introduce this idea to our usability team. We don't even know if this is a feature users would like so it's time to do some user research.

Other items I've heard about and would like to do user research include -

Information Design. Not really a cool new feature per say but I like reading blogs and articles about how people use content. We redesigned our user guides for the products on the Infinity platform. Now as our software evolves and user expectations evolve, it's good to stay current on the latest research.
Keywords. Add keywords to each PDF and then provide a way for users to search the user guides on our website. We've been looking into this for a while but have been having problems working around how we would do that with the current security settings in place (you have to login to see the user guides). Security issue aside, we have to see how this would affect our current work processes and what the return on investment would be.

However, I know we can't stop there. There is a whole field of information on readers that needs to be explored (you know, in between writing new documentation for all the millions of software product releases we have each month). I love that a part of my job is to look for new ways to enhance our documentation. So if you have any suggestions, tips, or tricks for Adobe Acrobat, please pass them on. Oh and if you have any knowledge of other tips and tricks for other PDF readers out there, I'd be glad to hear about those too. As long as the reader is free for our users, I'm willing to do the research on ways to enhance our user guides. Research on cool new user assistance features is about as cool as The Dark Knight (already one of my all-time favorite movies). In other words, it's too cool for school.

Selecting a 'Reader'

Justin Ward — Fri, 23 May 2008 14:33:00 GMT

In an upcoming release of our version 7 products, we are going to remove Adobe’s Acrobat Reader from the installation. Right now, if you do not have a Reader installed on your workstation, our install detects this and asks if you would like us to install Acrobat Reader. A ‘Reader’ is a free tool that allows you to view and print Portable Document Format (PDF) files. If you’ve ever opened a PDF online, you have some form of Reader installed. For example, you need a Reader to view the user guides on our website.

We’ve found that providing this option really isn’t necessary since nearly everyone already has a Reader installed, and because we want our users to have the latest version of their reader – something we cannot update between releases.

Available Readers
While Adobe’s Acrobat Reader is the most prominent (and most feature-rich), there are a lot of other free Readers out there as well. I’ve read some good reviews on these applications, but I can’t really recommend any because I’ve only used Adobe’s Reader. However, if you are interested in other options, a quick Google search will yield plenty of results. Wikipedia even has a complete list of free Readers and categorizes them according to operating systems.

Just keep in mind, you might be able to find a tool that takes up less space on your hard drive, or something a little faster, but that’s probably because it doesn’t have all the bells and whistles that come packaged with Acrobat Reader. For example, Foxit Reader's download size is 2.55 MB, which is less than half the size of Acrobat's, and Foxit promises to launch instantly, without any delay. That probably sounds appealing to most users, just be sure you aren't leaving any needed, and free, functionality on the table.

If you are interested in Acrobat Reader, you can download the latest version (currently 8.1.2) from the Adobe’s website at no charge.