I’d Rather Be Writing – Tom Johnson

This is a guest post by Cathy Wildhaber about her experience implementing a wiki in her department. Cathy is a technical writer in Kansas City. For the past 4 years, she has worked for a company that provides computer systems and services to financial organizations.

Ever take a look at some slick wiki technology and think “Wow, that’s really cool…I want one”? I did, and the results (an internal wiki for the documentation department where I work) were…less than stellar. Here’s how you can avoid my mistakes.

I had been working on a continuing education SharePoint site for the department. There was a wiki webpart available in SharePoint, and I became intrigued. What better way to help department members increase their knowledge about the profession than by harnessing our collective brainpower and talents! We could create collaborative summaries of training we’d attended! The intern could create a “new hire” section! We could have a knowledge base! How cool! Read the rest of this entry »

For those interested in learning more about wikis, Anne Gentle is giving a virtual presentation on documentation wikis for the NY Metro chapter of STC.  Her presentation is titled “Wiki-fy Your Doc Set: A Writer’s Role in Web 2.0.” Members are charged $5 and nonmembers $10. You can register through the following link: http://www.stcnymetro.org/events/messages/2009-016.htm

Can SharePoint 2007 be used as a help authoring tool? Maybe.

Giovanni from Italy asks the following about SharePoint:

I am assisting a colleague with a complete overhaul of an existing Help system. It is in RoboHelp, but has legacy topics that have to be maintained in Word. The Help is for call center and business office employees regarding the proprietary, in-house computer program. We recently got SharePoint, and I would like to know your thoughts on the pros and cons of Help in SharePoint. For example, can it be context-sensitive?

To provide some more detail, we don’t have any translations planned, although I suspect we will need to consider translating to Spanish at some point. There is a need to post PowerPoints and PDFs that are accessed through the current Help menu. We might have multiple authors (not sure).

We don’t need any conditional text , although I think it would be useful because we have several different categories of customers. I’m also advocating strongly for context-sensitive topics. We don’t need multiple outputs, not as it stands now, although I am in the process of researching content management systems and reusability, which would be a great boon to this group.

We also use Captivate and Articulate, which I would like to integrate into short show-me tutorials where appropriate.

Giovanni,

SharePoint is a good solution is if you have simple help content that doesn’t need to be printed, translated, or conditionalized. In the following two sections, I’ve outlined SharePoint’s strengths and weaknesses as they relate to help authoring. Read the rest of this entry »

Flossmanuals.net is a new wiki help authoring/publishing tool hybrid that, as far as I know, is completely unique. The site is more than a wiki. It allows groups of authors to create specific chapters independently. You can then remix the chapters into any arrangement and selection you want through a drag-and-drop interface. Finally, you can export the selection as a PDF file. Alternatively, you can embed the manual on a separate site using an API.

Flossmanuals -- a site that combines a wiki with a publishing engine

Read the rest of this entry »

At Doc Train, Stewart Mader was such a popular guy that both Scott Nesbitt and I interviewed him separately. I just listened to Scott’s interview while shooting hoops tonight, and I thoroughly enjoyed their exchange. 

Scott touched on many angles I didn’t cover and went more in depth. Here are several things that struck me: Read the rest of this entry »

Lately I’ve been converting my documentation over to a SharePoint wiki and have had days where I felt totally liberated and others where I wanted to go into my Control Panel and remove every Microsoft product I have installed on my computer.

Liberating

Here’s what I find liberating. Most wikis can easily degenerate into a chaotic disaster, with links nested on pages pointing to other links on other pages, with no clear sense of where you are or how deep the wiki goes. One writer at Doc Train told me her company’s wiki was an “unmitigated disaster.”

With SharePoint, you can get around this chaos by adding columns on wiki pages. The columns are similar to metadata fields for the page. You can add a drop-down box requiring the user to select a category for the wiki page, and the role, and any other ways you want to classify the wiki page.

Then you use SharePoint’s sorting and grouping functions to create various views for your wiki. These views use the columns/metadata fields to sort your pages by category, by role, or other methods. This is liberating because it allows you to impose order on what might otherwise become chaotic.

Read the rest of this entry »

I’m giving a virtual presentation to the STC-Phoenix chapter tomorrow at 6:15 pm Arizona Time (which right now is the same as PST). The topic of my virtual presentation is “Combining Social Media with Help Authoring.” See more details here. It costs $10 and should last about an hour. Even though it’s coordinated by STC Phoenix, anyone interested can sign up.

May 15, 2008 Update: View the PowerPoint for this presentation (.ppt).

Download MP3
Duration: 18 min.

Stewart Mader was one of the coolest people I met at Doc Train West 2008. He is a person driven by his enthusiasm for wikis. Read the rest of this entry »

Download MP3
Duration: 43 min.

In this podcast, I talk with Alan Porter, vice president of Operations at WebWorks, about the Web 2.0 technologies they’re using to reach out to their customer base. In addition to using blogs, wikis, and social networks to connect with customers, WebWorks also uses wikis to facilitate communication and collaboration within their company.

Alan says they consider themselves a “wiki-driven company” because the wiki drives the way they do business. WebWorks has an internal wiki (which replaced their old intranet), a projects wiki (used to communicate with their customers on project work), an external wiki for their help center (where customers can interact directly with developers and support), and a wiki for organizing their upcoming user conference.

Read the rest of this entry »

Sarah Maddox gives us a interesting glimpse into the life of an agile technical writer, or more descript, extreme technical writing, XTW. If you work in an agile environment, definitely check out these two posts:

• The Agile Technical Writer (I)
• The Agile Technical Writer II

(Although ffeathers is already in my feedreader, I missed these posts in the firehose of information and didn’t discover them until I read Anne Gentle’s latest post, How to be an Agile Technical Writer with a cool acronym like XTW.)

Here are a few excerpts from Maddox that hit home with me:

Things change, and we need to change with them. If we spend too much time setting requirements in stone, they’re out of date by the time we write the software. And then there’s no hope that the documentation will be up to date.

Totally agree with this one. I went from a traditional all-requirements-up-front environment to an agile environment, and the difference in software quality is pretty astounding. I’m convinced that people don’t know what they want until you deliver them an actual product. Read the rest of this entry »