From the Doc Side : tools

Forget Best-Selling Audio Books, Listen to Our User Guides for Free!

Lindsey Robbins — Tue, 20 Oct 2009 14:08:00 GMT

Did you know you could listen to our user guides read out loud for free? Well, if you have the free Adobe Acrobat Reader or even the full Adobe Acrobat installed on your Windows computer you have the ability to not only read our guides but listen to them as well. It's a little known feature that may be of use to you.

In Adobe Acrobat Reader, on the menu go to View, Read Out Loud. You can select to listen to the entire document or just the page you are on. Adobe uses the basic Windows voice settings so if you aren't able to hear anything, go to your Control Panel, Sound and Audio Devices, Audio tab. On the Audio tab, ensure you have a device selected for the sound playback.

If you want to adjust the voice or playback speed for the read out loud capability, go to Control Panel, Speech, Text to Speech tab. I personally went with Microsoft Sam on my computer, I like his deep monochromatic voice. If only they made a CP-30 voice.

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.

Rise Above the Tools

Lindsey Robbins — Tue, 19 Aug 2008 19:56:00 GMT

It’s not about the tools. This is what I always tell myself and this week is a prime example of why it’s more important to rise above the tools and focus on what you’re getting out of it than to focus on mastering the tool. Why you ask?

Well because sometimes, even with your best intentions, tools can do weird things and laugh at you. In those times, you need to be smarter than the tool, or just laugh at yourself and try again tomorrow.

Let me set the scene –
I’m working on generating help files for EE/SIS. We were having an issue with some hypertext markers we use to link one part of the help file to another. I realized I needed to change part of the marker.

Specifically, I wanted to change

gotolink //Ntpd/docs/EA_FE/EE_FE_SIS_777/manuals/…
to
gotolink //Ntpd/docs/EA_FE/EE_FE_SIS_777/Manuals/…

yup, all I wanted to do was change the lowercase m to an uppercase M.

Then, I clicked the Edit Marker button.

What did Adobe FrameMaker do?

It changed Manuals to smanuals. Yup, you read that right, it completely changed a word on me.

smanuals

What in the world? I think I made the god of tools (whom we dubbed Mechanisis) really mad because in all fairness Adobe FrameMaker has been good to me the past few years. This isn’t normal. Software doesn’t usually change words on you. What do you do in these situations (besides make your cube mate laugh at you so hard he was crying)?

You rise above the tool, you fall back on your common sense and experience to remember that you can endure even the strangest of tool interferences. Software is always going to be evolving and changing. Even experts on explaining software have hiccups in the road. It’s what you do to move beyond the problem that makes you successful.

And you know what; today I generated the help file after figuring out a work around. Not only did I overcome the smanuals, but I managed to fix the error we were having with our broken hypertext links.

Call 'em smanuals or manuals, I don’t care as long as I can reach a happy ending.

Jumpcut - Online Video Editing Tool

Lindsey Robbins — Mon, 28 Jul 2008 13:50:00 GMT

Now that our team’s Docs Day 2008 (team training day) is over, I can start sharing all the fun surprises I had for them in my presentation. I presented on my trip to the Society for Technical Communication Summit in June. I’ll be posting reviews on each presentation I went to as I promised in an earlier post. In the meantime, I wanted to share a fun new tool I used for the lunch time entertainment.

I found this site – Jumpcut http://www.jumpcut.com

Jumpcut is a website that makes adding, editing, and sharing video online easy. In 2006, the company was acquired by Yahoo but I don't think it's taken away from this fun, feature rich site. For me, the easy to use editing part was the reason I chose this site. I had embarrassing footage of me doing the Rocky impersonation in Philadelphia and wanted to add the Gonna Fly Now music to create a silly video of me for my team to laugh at. Then when I started playing on the site it was easy to add photos, more music, and transitions. The only issue I came across was trying to figure out how to transition the music. Also cool, people can remix your video or you can give them permission to edit. The features are all easy to use and the learning curve isn’t that steep. In the end, you have a **free** video you can share with others.

At risk of further embarrassment, I’ll post the video here. Warning – it is 8 minutes long! (I got a little out of control). Also, in the beginning I was making fun of the opening session by posting a picture of each person who presented something before the keynote speaker. It just went on and on! Once you get past those though, it’s all pictures of how much fun I had in Philly.

Enjoy a good laugh on me!

A Great Visual Communication Resource - Worldmapper

Lindsey Robbins — Tue, 15 Jul 2008 16:45:00 GMT

This post is a little off topic from documentation but it's a great resource I came across from my alma mater's listserv.

Introducing... Worldmapper! http://www.worldmapper.org

According to their website, "Worldmapper is a collection of world maps, where territories are re-sized on each map according to the subject of interest… There are now nearly 600 maps."

Did you read what I read? 600 maps for us to click around, play with, and in general become more aware about the world we live in. I especially recommend you spend some time learning a bunch of cool things in the Map Categories section.

366 of the maps are available as PDF posters. This is definitely a great resource if you need a visual to communicate an important point.

Here's an example of a map based on total population…

And another example, based on road traffic deaths…

I guess the traffic in Charleston doesn't seem so bad now.