I spent much of last week with my head inside a Mediawiki skin (when I probably should have been working on another project). I’m not entirely sure what it is, but I sometimes get fixated by technical problems I can’t seem to solve.

I first customized the FraternalRelief Mediawiki skin to match my organization’s home page. My customization wasn’t too bad, but I saw a few errors, and when I queried a forum, they told me FraternalRelief was no longer compatible with the current version of Mediawiki. Who would have thought.

Fine. I found a compatible Paul Gu theme and customized it again to match my organization’s site. But during a design review meeting with my team, I brought up the fact that the theme was licensed under GPL. I don’t understand the finer details of GPL, but the thought crossed my mind that perhaps GPL would require me to make my customization available to the world. A Mediawiki forum moderator said that would only be the case if I were trying to distribute the skin — then I would have to give it away for free. But still, I wasn’t sure. Read the rest of this entry »

I mentioned in a previous post that I think traditional help authoring tools are becoming less and less viable for robust software projects in which multiple subject matter experts in distributed locations need to collaborate, and when these same subject matter experts need to own the documentation after release.

I think traditional help authoring tools (HATs) will fade in place of more collaborative tools like wikis

This wasn’t just a fleeting thought. I spent the last couple of days last week getting buy-in from project leaders on wiki formats for all of my upcoming projects. I thought we might be using Confluence in addition to Mediawiki at my work, but because learning and maintaining two different wiki platforms is onerous for both engineers and content contributors, we decided to stick with just Mediawiki.
Read the rest of this entry »

If you work in a large corporate environment, you’re familiar with restrictions about accessing production servers to make updates or additions to your help content. To touch anything on a production server, you have to go through the change release process, which requires a lot of paperwork and procedural hassle. Almost no project manager sees documentation as important enough to release a new version of the software into production on account of a need to update the help.

And yet, I regularly need to update the help after the application is released. For example, in the previous project I was writing about, the Local Unit Calendar, after release I learned about a bug in production. I received a couple of questions from a user, and the answers weren’t in the help. I had an error in the section about changing calendar color. And I needed to add some more instruction in another section.

When I explain to system engineers that I need a server for my help that I can update on the fly, they always ask why. Why can’t I just include my help content in the application? However I explain it, the reasoning always comes off sounding like an excuse for not being able to finish my work on time for release.
Read the rest of this entry »

Recently I’ve been working on a simple calendar project that uses a wiki for documentation. Although I’ve heard a lot about using wikis for documentation, and have even used them in the past, I ran into a few surprises this time. Read the rest of this entry »

Although many people put blogs and wikis in the same social media category, blogs and wikis are actually quite different. Blogs are individually authored mini-magazines or journals where one author (or sometimes a small authoring group) crank out article after article (or entry after entry) usually with a common theme. After each article is published, the article is considered done and the author moves on to newer pastures, always hunting for the next story, formulating the next insight, thinking about the next post. Readers can comment and subscribe by RSS.

Wikis, on the other hand, are a platform for groups to collaborate on an information project, such as documentation, technical specs, or other reference material (e.g., Wikipedia). One author isn’t just cranking out all the information. Multiple authors are contributing chunks and pieces, linking from one page to another, making edits on each other’s content, diving deeper where necessary, and moving toward the idea of a more complete information product. Wikis are rarely ever done. They are successful only as much as they tap into the collective intelligence of a group. Read the rest of this entry »

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 »