I'd Rather Be Writing - Tom Johnson » Wikis

Design Fixations with Mediawiki Skins

Tom Johnson — Mon, 14 Dec 2009 06:46:53 +0000

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.

Then another team member brought up another point. He said my customization should either look exactly like the original site or it should be noticeably different. No cheap knock-offs or it will throw readers off. I had to agree.

So after the meeting I commenced to pull apart the default Mediawiki skin (Monobook) piece by piece in an effort to understand it. I copied over the stylesheets and layout of the page I was trying to match. And then one by one I copied over chunks of Mediawiki PHP code, trying to understand what each code snippet does.

I copied the source code of the organization page I was attempting to clone. I downloaded all the stylesheets. I pulled down about two dozen images referenced in the stylesheet. I then commenced to integrate the code into the Mediaskin. After about a day and a half, I finally cloned it.

The problem is, Mediawiki has tons of additional components that a regular website doesn’t. This is what most people don’t understand when they want to convert their regular HTML website to WordPress — WordPress has a lot more components, each with unique styles. And some of the components only appear at certain times, under certain conditions. So while I cloned my organization’s page into a Mediawiki skin, I also have many styles that I need to create. (I wish I could show a screenshot here, but I can’t since it’s behind the firewall.)

I am starting to like working with Mediawiki as much as I like working with WordPress. Last week the world could have disintegrated around me, and I wouldn’t have noticed or even pulled myself away to look.

I don’t get fixated with writing help topics in the same way. Mostly writing helps topics is a chore. It’s not what I wake up dying to do. But to design the skin, the frame around which the content will display, that’s the fun part. It’s what I’ll do despite all obstacles.

This is not to say, however, that I have aspirations to be an interaction designer. I do love to write. It’s nearly 1 a.m., and I couldn’t sleep because I wanted to write. But to be free to design and configure the publishing platform for my content is something that, at times, mesmerizes me.

Blog Sponsors

Ramping Up on Mediawiki

Tom Johnson — Mon, 07 Dec 2009 05:13:27 +0000

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.

Surprisingly, when I explained the need to collaborate with multiple contributers, and also expressed for business departments to own the documentation after I created it, the senior leaders gave me immediate approval to use a wiki format.

So I’ve been ramping up on Mediawiki lately. In some respects Mediawiki is similar to WordPress, and in others it’s not. For example, both WordPress and Mediawiki are open-source PHP web-based platforms with MySQL database backends. After creating a database and user, you set up the sites through an installer script and configure the display through CSS.

Both platforms have themes/skins that you can download and apply to your wiki. Both platforms have thousands of plugins/extensions that will extend the functionality of the software. Both platforms have vibrant online communities with thousands of users participating in forums, blogs, and other groups.

However, there are also some key differences between the two. The main difference is that Mediawiki has no user interface for managing the content, whereas WordPress does. With Mediawiki, you work a lot with a file called localsettings.php, which you have to FTP back and forth.

Additionally, with Mediawiki you sometimes search for the files you want to modify and then edit them within the browser interface. Mediawiki has a lot of namespaces, so creating a page with a certain prefix before a colon puts the page into a particular group and it gets treated differently.

I previously thought wikis were fairly primitive and limiting in terms of format. I’m now realizing that wikis — at least Mediawiki — is incredibly robust. There’s a lot to learn. For example, to impose structure on a wiki, you can label pages with categories and subcategories. When you add [[Category:Oranges]] to a page, it puts the page in a category called Oranges. Then you can dynamically pull together all pages with this category label. And you can add subcategories by opening the subcategory page and adding the parent category tag.

“Category” is in a Mediawiki namespace, and there are dozens of these namespaces. Through the Category Extension tree, you can automatically show all pages within a category in a collapsible tree. The tree uses AJAX to collapse and expand. To install the extension, you add some code to your localsettings.php file and upload the extension files to your /extensions folder. You can also access a special page for browsing categories by searching for special:categorytree.

Templates are snippets of reusable code. For example, if you have a note style that you want to reuse again and again, you create a new page like this: [[Template:Note]], and add your style. Then when you want to use your template on a page, you just add {{Template:Note}} and the code appears. It’s essentially a php-include.

I only add this detail here as an example of the underlying robustness of the software. Previously I thought wikis might be limiting because the formatting options seemed so primitive — either bullets or numbers or headings, and not much else. Now I realize that I have so much to learn. I’m only on stair three of about a hundred stairs.

Over the next year I’ll have my head deep in Mediawiki, so expect to hear more about it from me on this topic (and wikis in general).

Blog Sponsors

Wikis and the Holy Grail of Content Independence

Tom Johnson — Tue, 03 Nov 2009 03:12:38 +0000

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.

And yet, I sometimes don’t find out about an application until two weeks before the application goes live and needs documentation. Although I need to create video tutorials, the interface isn’t frozen until the application goes into hardening and becomes a potential release candidate.

If the materials need to be translated, the Translation department requires at least a month of turnaround time. If the content will be printed and sent out to users, I may have to get the content approved from a department that ensures message consistency.

If subject matter experts don’t take time to carefully review the material and video scripts before release, there’s a good chance the help will contain some inaccuracies. Project managers and quality assurance engineers rarely have time to review help material the week before a release. If I don’t submit the help content to peers for a style review, there’s a possibility that typos or inappropriate formatting will also sneak through.

In short, there’s a host of reasons why the documentation might need to be updated after the application is released. If I could access the help content and continue to add and adjust it at any time, independent of application releases, it makes documentation less of a time crunch the night before (for example, to finish the video tutorials for the calendar app., I stayed up until 5 a.m. the night before).

The concept of having control over your help content, to update it at any time, is what I’m calling content independence. Establishing content independence in your publishing environment may be a battle that can take years. For example, at a previous job, it took five years to finally convince architecture that we needed and deserved our own independent folder on a production server.

In my current situation, I’ve pursued publishing routes in infrastructure that would enable on-the-fly updating, but for two years in a row I’ve come up empty-handed. With wikis, I think I’ve finally found the holy grail of content independence.

By nature, wikis sidestep the problem of file transfers, because you can always immediately access and update the content through the browser interface. For content outside the interface, such as PDFs, SWF files, or diagrams, which you can’t code into wiki syntax, you can still upload the video tutorials through Mediawiki’s file upload utility (and probably through a lot of other wiki interfaces as well).

Mediawiki's file upload utility

The interface file upload utility gives you a tunnel to production without having to go through change release!

Note: You can’t upload every type of file through Mediawiki. HTML files and Javascript files, for example, are usually forbidden file types. Also, the file upload is one at a time, so a traditional webhelp system generated by Flare or RoboHelp wouldn’t be uploadable through a wiki’s file upload utility. But if you’re using a wiki for documentation rather than a static help authoring tool, this isn’t an issue anyway.

To enable file uploads in Mediawiki, you have to make a few tweaks to your localsettings.php file. You may have to adjust your settings in the php.ini file too. And if you want to embed your videos, you may want to install a Flash extension. I’ll include instructions for doing all this in another post. But basically, despite the drawbacks that wikis involve, they provide you with an invaluable advantage in help authoring: content independence.

Blog Sponsors

A Few Surprises in Using a Wiki for Documentation

Tom Johnson — Thu, 29 Oct 2009 14:40:15 +0000

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.

1. Authoring directly on a wiki screws up the history of updates.

The way wikis work, every time someone makes an edit, it’s recorded in a history for the page. When I write, I make a lot of little updates here and there, not just within one section, but across multiple sections. I can make 10 updates, apparently, in one minute (or so someone told me, who complained that I was mucking up the revision history). I like to hit Save Page often, especially if I have the whole page in edit mode (Microsoft has taught me well). When I save frequently, the version history becomes somewhat useless, as it just shows my name a million times.

Version history isn't so useful when you use the wiki as an authoring tool

Perhaps the solution is to author on a practice wiki and then transfer finished blocks of text to the production wiki when you’re ready to collaborate with others on the content?

2. The text width is longer than St. Pete beach.

I realize this is probably a setting I could control through a wiki stylesheet, but the default width of text for Mediawiki pages spans about seven or eight miles. This makes it difficult to read.

Wiki column widths are often really wide

Wikipedia has the same problem with length. The optimal width for a column of text is about 75 characters in length (less, actually).

(Here’s St. Pete beach, by the way. Next week I’m going on vacation to Florida and am definitely strolling down this long beach, which is my favorite. I’ll be thinking of Mediawiki while I walk.)

St. Pete Beach — photo by Hanny Heim

3. Community members seem more likely to make little edits rather than create entire pages.

Last week I was at WebWorks in Texas, and I asked Anne Gentle why no one has developed a plugin to convert from wikis to a help authoring format. It makes sense that people would collaborate on a wiki, finalize the content, and then export to a more flexible format, right? Anne felt there wasn’t a business case for creating such a plugin. What?

But after working with a wiki on this project, I see what she’s saying. In my situation, members of the community aren’t going to contribute tons of content. I did receive some help from another volunteer in the beginning, and he wrote several small sections. But when I took over the page with major edits, revisions, and other additions, it kind of pushed him away.

Collaborative authoring isn’t so engaging if two people are hacking away at the same page, changing what each other writes. Authoring this way detracts from one’s sense of authorial ownership. Instead, I believe it’s more common for a single author to create the bulk of a page, and then have the community add edits, a few sentences here and there, tips and notes. The baker creates the cake; others add icing. By and large, there’s one baker per page (at least that was the case with my project).

4. Navigation is cumbersome.

Mediawiki organizes the content of each page into table of contents automatically. The table of contents can get somewhat long and cumbersome (even as simple as the content is), if you aren’t paying attention.

Writing in a wiki format forces you to think carefully about the organization of your content. If the page gets too long, you can break it up into multiple pages.

You have to think carefully about the navigation

The best-practice paradigm of topic-based authoring — authoring content in small chunks that you can manipulate and single source — doesn’t seem to apply to wikis. If you chunk each section as its own page, readers will bounce from page to page to page. It will become a dizzying experience of clicking and clicking.

Perhaps there’s a way to pull in sections from other pages, but I don’t know how to do that yet. Maybe wikis break down when it comes to single sourcing for multiple roles or audiences. Not sure here.

5. Making updates is incredibly simple.

If there’s a major strength to wikis, it’s the ease of making updates. For example, in looking over my local unit calendar help wiki as I wrote this post, I noticed a couple of inaccuracies. I nonchalantly clicked Edit next to those sections and made updates. I absolutely love the ease of updating a wiki.

For people who need to review the content, it’s easy for them to make changes, add comments, and proceed section by section. Don’t underestimate how important this aspect is in the authoring process. I’ve written before about the importance of living documentation – documentation that you update regularly based on user feedback, problems, stories, and other questions. Because a wiki is a live format, you can tap into it at any time and make changes.

On this topic, also see John Hewitt’s excellent post on living documentation and Stewart Mader’s post, Wiki: A More Productive Medium for Living Documents.

6. Wikis are a web format.

Although I wasn’t too enamored with wikis when I started this project, I’ve come to like them more and more. One aspect of wikis that draws me in is the web format. I’ve realized lately that I enjoy web design. A lot. I like working on the web. I like stylesheets and links and jquery effects and layout, navigation — everything.

I realize that authoring in a tool like Flare produces HTML output, which is a web format, but I dislike the static nature of authoring in a help authoring tool and then uploading the content to a file directory to appear in a browser. There’s a disconnect. It doesn’t feel like web authoring, even if it’s published on the web. It’s more like static HTML authoring.

Although I didn’t fallen in love with wikis in the past, the integration with the web may be enough to convert me. Part of my problem with wikis previously was my expectation that users would contribute more. When that expectation wasn’t fulfilled, I wondered why I was using a wiki.

Now I feel differently. For one thing, wikis ensure a separation of help content from application code. This means I can have access to the help even after applications are released. This is something I feel strongly about. Help content should not be packaged with the application code. When help is packaged with application code, these are the results:

little or no interaction with the user community.
uncorrectable errors that can’t be fixed.
a mindset of it’s-released-so-now-I’m-done.
no time for translation or video tutorials (because the app isn’t frozen until the week before release).

7. Wikis provide a new language to learn.

Wikis are supposed to be easy to author in, and for the most part, they are. However, they also provide a new syntax and language to learn. That can actually make authoring more fun. For example, look at this little player button in the image below.

Making an image link to a webpage

By default, in Mediawiki, images link to themselves (or to a larger picture of the image). In this case, I needed the player button to link to the video tutorial, not an image of the player button on the file:image page. You would think that making an image link to another page would be easy in wiki syntax, right? Actually, it took me 10 min. to figure this out. Here’s the syntax:

[[File:Videoplayer.jpg|link=http://lds.netdimensions.com/ldslive/nd/fresco/repository/html/luc/subscribetoacalendar.html]]

In retrospect, it seems pretty simple. But the link= part I had to dig up.

Concluding thoughts

Strangely, I started this post somewhat antagonistic against wikis, and as I’ve reflected on them, I’m now considering using wikis exclusively. I don’t know what happened, but I like the direction wikis take me. It’s the direction of the web.

By the way, if you have any feedback on how to improve my calendar help wiki, please let me know.

Blog Sponsors

How Do Blogs and Wikis Fit Together?

Tom Johnson — Tue, 08 Sep 2009 06:10:55 +0000

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.

How exactly do these two formats fit together? In Conversation and Community, Anne Gentle says that the blog can often be a conversation starter, the medium that opens up communication among people. Your blog can attract outsiders and draw them in to participate on a wiki or other involvement.

Seeing how these two formats and activities fit together provided an Aha! type of moment for me last week. We have a community projects wiki where a lot of developers, QA engineers, and others interact on a technical level, either compiling requirements, designs, or other details about the projects they’re building. The site also has a blog component, but the blog doesn’t always address the existing projects. In fact, the blog mainly consists of random IT topics written by people in our department.

I realized (not that it’s really much of an insight) that in this situation, the blog should act as a companion to the wiki. While the wiki has project details and other specs, it’s not the motivational piece. It doesn’t build trust, inspire people to join the community, or even communicate that much to those outside of the layers of its structure. Just as a charter or project requirements documents rarely inspires anyone to volunteer for the project, the same might be said of wikis. But that’s not the wiki’s job. It’s the blog’s job. The blog serves as the human-focused news stream for sharing announcements, insights, developments, stories, and other details about the projects going on in the wiki. They’re a perfect fit, and one fuels the other.

Blog Sponsors

Implementing a Department Wiki? A Writer Shares Some Dos and Don’ts (Guest Post)

Tom Johnson — Tue, 30 Jun 2009 13:33:10 +0000

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!

Wiki Dos (and Don’ts)

I immediately set up the webpart, learned how to create and edit pages, and provided a training session for my coworkers. I gushed about the endless possibilities, and then sat back and waited for the quality content to roll in. It didn’t.

Where had I gone wrong? Through the power of hindsight—and the research I should have done before I launched the wiki—I’ve come up with a few guidelines to follow next time. Perhaps you’ll find them helpful, as well.

Start with a clear purpose (a.k.a. Avoid the “if you build it, they will come” fallacy)

If you get starry-eyed over a wiki and then try to come up with ways you could use it, adoption is likely to be weak, as was the case in our department. If, however, you have a genuine process inefficiency or lack of resource that a wiki could help solve, you have a much better chance of success.

This phenomenon is best described by Mark Shead. He defines two types of technology users. Members of the first group identify a problem and then seek a technology to resolve it. Members of the second group, on the other hand, start with a cool new technology and then look for a way to incorporate it into their lives. When members of the first group adopt a technology, they are more likely to stick to it. Members of the second group often abandon the technology after a short time.

Prove how the wiki can benefit users

To embrace a wiki, users must first see how it will benefit them. Provide examples of how their real-world work could be moved to a wiki, and show how it could result in more efficient processes.

Ease existing fears about the wiki

People unfamiliar with wikis may fear that a platform in which any person can edit or delete any page will be chaotic. They may feel concern that a wiki could easily devolve into a free-for-all.

In a company wiki, the accountability for contributions and edits is much higher than in a major public wiki like Wikipedia—no one could leave anonymous spam. And while a small company wiki would likely not have the system of checks that Wikipedia employs, most small wiki communities tend to be naturally self-regulating. Chaotic editing and questions of ownership tend to be non-issues.

Provide proper training

If members don’t understand the broad concept of a wiki or the specifics of creating pages and setting up links, they won’t use it. Be sure to train users on what a wiki is (its purpose and what it’s good for) as well as on the wiki tool itself (how to create pages and set up links).

Don’t make it a chore

Don’t force the wiki upon department members. A lack of posts or edits by a particular member does not necessarily mean that the member is not finding value in the wiki.

Nurture your wiki

A wiki needs care and attention. Having an official “administrator” could imply that content is being policed, but you should ensure that someone performs a few maintenance functions:

Introduction of a loose organization or structure (perhaps in the form of a home page that links to broad categories).
Periodic checks to ensure that all pages can be found easily through links to a main page.
Periodic checks to weed out any spam or mean-spirited contributions.
Acknowledgement of good ideas, sorting of feedback, and implementation of suggestions.

Use metadata

To keep your wiki well-organized and usable, incorporate metadata. Metadata allows users to sort by category to quickly find what they’re looking for. Many wiki programs allow you to require that metadata be selected and allow you to define your own metadata. Other possibilities for metadata include content stages (can indicate whether the page is new, developing, or complete) or audience tags (can indicate whether the page is primarily for management, administration, or developers).

Broadcast updates

A system that notifies members when information has been added or changed will remind users that the wiki exists, and it will help ensure that the content is current, correct, and relevant. Notifications could come in the form of an RSS feed, or they can be as simple as an email alert. Users may prefer to receive a daily or weekly digest of changes, rather than notifications about every single change.

Encourage participation

A good way to encourage participation in the wiki is to enlist the help of a select few. You may select the most well-respected and established veterans of the department, or the enthusiastic early adopters of each new gadget, or the department members most willing to share their opinions. Often these individuals can pave the way for the rest. Recruit them to help get the wiki started; the rest of the group may well be more willing to participate after ground has been broken.

Blog Sponsors

Anne Gentle to Give Virtual Presentation on Wikis on Thursday, April 23

Tom Johnson — Wed, 15 Apr 2009 20:03:44 +0000

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

Blog Sponsors

Can SharePoint 2007 Be Used as a Help Authoring Tool?

Tom Johnson — Thu, 12 Feb 2009 05:50:17 +0000

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.

SharePoint’s Strengths

SharePoint has Web 2.0 features, such as blogs, wikis, and RSS feeds.
You can define granular permissions for user access based on Active Directory.
The document library feature provides a robust repository to store and manage all kinds of help files (provided users can access the site).
You can manage your help independent of the server your application runs on. (This allows you to make updates without going through a change release process.)
Multiple authors can contribute content at the same time (and it’s easy to do so.)
You can customize the look and feel of the site based on CSS standards.
With podcasting and blogging kits (additional add-ons), you can embed flash videos in posts, allow users to subscribe to comment threads, and more.
You can add metadata (“columns”) to any content, and then sort, group, or filter the content based on the metadata.
You can arrange wiki topics in a list format based on custom-added metadata/columns. This helps avoid the confusing navigation maze that befalls so many wikis.
You can customize search scopes so that users search only wiki content, or only blog content, or other site folders. (All scopes are available in a drop-down.)
SharePoint has a wide community of support across the globe.
You can integrate additional web parts (many third-party) that enhance SharePoint’s functionality.
DITA content can be manipulated in SharePoint. (See DITA Exchange.)
Built-in site metrics allow you to see details about specific users (but the metrics tool has limitations).
Calendar and task functionality integrate with your Outlook calendar and task list.
You can create audience-targeted text based on groups you set up.
The blog provides a convenient platform for release notes and other post-release information.
You can create multiple views of the same content based on custom metadata.
You can integrate a site-wide search for all site content (for example, online help files, wikis, blogs, Word documents).
SharePoint allows you to continually add help topics on a daily basis without recompiling or regenerating the help system.

SharePoint’s Weaknesses

SharePoint does have its weaknesses. It’s somewhat of a Swiss army knife: it has an impressive breadth of capability but doesn’t do any one thing particularly well. If you are planning to use SharePoint as a help authoring too, the following are SharePoint’s weaknesses:

The default blog doesn’t provide a “Read More” tag nor does it allow users to subscribe to comments (unless you configure a workflow through SharePoint Designer, which unfortunately is a confusing process).
Customizing the look and feel of the site is challenging.
Customizing the search scopes is not straightforward.
SharePoint doesn’t allow you to export blog posts, wiki topics, or other content into a printable format.
SharePoint doesn’t enable you to apply conditional text for multiple outputs. (As a website, there are no independent outputs.) Note: You may be able to do something with the Content Query web part, but I’m not sure.
SharePoint doesn’t work as a translation management tool.
The interface doesn’t provide an expandable/collapsible tree-like navigation on the side.
Wiki pages don’t allow simultaneous edits by different users. If two users edit the same page, one user receives an error when saving the page. (However, multiple authors can, of course, edit different wiki pages simultaneously.)
The blog can break easily if you delete the wrong field (and the only fix is to reinstall the site).
Custom columns that you add to wiki pages are exposed in full view, but not custom columns on blog posts.
Formatting controls are primitive. For example, continuing lists after inserting notes or images can require you to manipulate the source code.

My Overall Recommendation

Overall, SharePoint can be a good solution for help content, but it certainly has limitations. If creating a comprehensive printed manual isn’t necessary, it can be an attractive format because you can take advantage of the blog and wiki formats, which do function adequately. If you have multiple authors all contributing content, or a team that needs a dynamic way to exchange information, SharePoint is a good choice.

On the other hand, if you’re tasked with building several role-based guides, and you need both online help and printed manuals, SharePoint won’t work for you. But remember, the printed manual is dying. You could get away with some quick reference guides instead, referring the user to the SharePoint site for more advanced questions. (You’ll still always get the question, “Where can I print all this out?”)

Note: You can actually create a view in SharePoint that compiles all the topics in a way that looks manual-like, and you can copy and paste it into Word without losing much formatting. But you won’t have any cross-references or index, and there aren’t any styles that come over that you can manipulate (just inline styles). In a sense, then, you can have a printed manual available to those who need it, but it won’t be pretty and will require some clean-up each time. Still, if no one really reads the manual anyway …

Now, about context sensitive help. I have avoided this topic because I haven’t experimented much with it. It depends on the format you’re using for your help (blog, wiki, page, or other content type), but pretty much everything in SharePoint has a permanent URL. The only way to integrate context-sensitive help would be to manually code your application’s help buttons with the URL of the appropriate SharePoint page. This might work, but the entire site will load each time, with the full sidebar. You can’t hide the sidebar and provide an lighter view of the content.

Showstoppers with SharePoint

For me, SharePoint provides three main showstoppers:

Lack of printed export capability. Someone always asks for a printed copy of everything, even if they don’t use it. That person usually asks the project manager, who assumes or expects that the help content should be available in a manual for the user. The project manager doesn’t understand the difficulties SharePoint poses with this.
Inability to conditionalize text for role-based guides. Sure, SharePoint allows you to create different views of the content, so you could have different online perspectives of the topics, with different table of contents. However, if the user searches for content, the search results will return all the information on the site, regardless of the view. Since users primarily search for information, this poses a problem.
Lack of context-sensitive help. I don’t want an entire SharePoint site to load each time a help topic is called from within the user interface. That seems clunky to me.

Despite its shortcomings as a help authoring tool, the SharePoint blog works great for a team site. It provides an online platform for discussion and enables collaboration.

Blog Sponsors

FLOSSmanuals.net: A New Wiki Help Authoring/Publishing Tool Hybrid

Tom Johnson — Sat, 06 Sep 2008 05:52:12 +0000

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

FLOSS stands for Free/Libre Open Source Software, and this site announces itself as a host for open source software documentation (“free manuals about free software”).

Why not use traditional help authoring tools? Often times open source software projects can’t afford the expensive authoring tools more commonly used to document commercial software. Additionally, developers — who often write the documentation — don’t want to learn complicated authoring tools. The wiki interface is simple yet flexible. Publishing multiple versions of guides is easy. Read more about FLOSSmanuals.net here.

In exploring the site, I think the concept is impressive. It’s the next generation in wiki authoring. However, right now the site is very young. Additionally, by limiting the scope to open source, the authors limit their potential for adoption. The same software could have market appeal for commercial group authoring situations.

Anne Gentle is one of the go-to people for information on Flossmanuals. You can read the results of their “booksprint” (a long documentation writing party) on Anne’s blog.

Keith Soltys wrote about Floss and linked to numerous other writers, including Charles Jeter and Janet Swisher. We also talked about FLOSSmanuals.net briefly on the last podcast.

—-

Update: I just published this post and Jane looks over my shoulder and says “Floss manuals? They teach you how to floss?”

Scott Nesbitt Interview with Stewart Mader on Wikis

Tom Johnson — Tue, 20 May 2008 12:00:43 +0000

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:

Stewart’s Wikipatterns site shows wiki practices and techniques that work well in organizations. It’s a wiki that anyone can contribute to. Initially he started with about 30 patterns (best practices), and through the community influence expanded to more than 100.
Stewart is so enthusiastic about wikis that he posts his slides and talks on his site because, although someone could conceivably steal his Powerpoints, he feels the benefit of gaining a new wiki convert through the Powerpoint theft is worth it.
Stewart wrote his Wikipatterns book using a wiki, and the editors loved it because they could quickly see Stewart’s progress in writing the book. Stewart was also able to write the chapters he felt like writing (rather than proceeding chronologically). And because he travels a lot, the web-based wiki allowed him to write from anywhere he had Internet access.
Stewart uses the term “security guards” to describe people in organizations who are defensive about contributing to wikis – they spend their energy keeping information from others. His argument to these people is that hiding information makes them less powerful than sharing it, because when you share information, you demonstrate your knowledge and allow others to build on it. People begin to seek you out because they perceive you as an expert on a subject. You make your expertise visible.
A lot of people aren’t familiar with the term “wiki,” even though wikis have been around since 1995. When this happens, try calling the wiki a “collaborative space.” By the way, wiki means “quick” in Hawaiian. The unconventional name reflects the unconventional technology. And it is quick to write, edit, and publish content on a wiki.
Stewart’s strategy for wiki adoption in organizations is to start small and restrict wiki access to a limited group of people until the demand rises from the outside. He says many organizations make a wrong move by opening wiki permissions to everyone at once.
Stewart says that big companies often invest in expensive, complex authoring tools/systems. Employees resist adopting these new tools because of the learning curve. In contrast, people are much more willing to embrace a technology that’s simple.

Overall, while the wiki does have some limitations, wikis present such a major collaborative, community-based shift in the way organizations work that the benefits far outweigh any disadvantages. Stewart said he can’t think of any organization that couldn’t benefit in some way from a wiki.

For more on wikis, see Stewart’s blog, Grow Your Wiki.

(See, you can learn a lot listening to podcasts even while playing basketball.)

Also, coming soon: Screenshots of my new wiki/blog-based SharePoint help site.