SharePoint for documentation projects

Most of the Technical Authors I have met don’t have a good thing to say about Microsoft SharePoint. In many ways, it represents how not to publish content online. It is seen as encouraging people to move print-optimised documents (Blobs) around, rather than units of content (Chunks), and users are typically left to rely on search to find which document contains the information they are looking for.

For all those issues, SharePoint may still have its place – for managing documentation projects.

Continue reading

Getting information from Subject Matter Experts

Flickr photo an interview by illustirInterviews with Subject Matter Experts (SMEs) are some of the most useful sources for Technical Authors when they are gathering information about a product or procedure. This often involves asking a developer or departmental manager a series of questions focused on the types of questions end users are likely to ask.

Interviewing is one of those dark arts that Technical Authors pick up over time – techniques for getting SMEs to find the time to speak to you and review your drafts, ways to avoid conversations meandering away from what the user will want to know, tools for capturing the interview, and so on.

So what tools should you use?

Coming armed with biscuits (cookies in the USA) is probably the most effective tool! After that, the most useful tool to have is a voice recording device. If you have a smartphone, in effect, you have a digital voice recorder. There are many voice recording apps for both iOS and Android, but the one we like is Recordium.

Recordium

In addition to recording audio, Recordium also enables you annotate the voice recording. You can highlight and tag certain parts of audio recordings (for example: to indicate a new topic or to mark sections that relate to definitions of terms etc), and add attachments to those sections as well. You can use it, in effect, as an audio-orientated note clipping application, similar to Evernote.

Recordium also enables you to vary the playback speed. We’ve found this useful when SMEs are using specialist terminology – you can slow down the recording to check what it was they actually said. Listening at a faster speed is also a useful way of reviewing a recording quickly.

Technical Authors still need to transcribe sections of the interview, so it becomes text. Unfortunately, Text-to-Speech applications still have some way to go. Dragon Dictation is available for Apple devices, and ListNote offers similar functionality for Android. However, even if you are just a two fingered typist, you’re probably better off transcribing the audio yourself.

Are there any other apps you’d recommend? Let us know.

New software that might interest Technical Authors

Here are some new tools we’ve found that might interest Technical Authors.

Google Ripples

Google Ripples is a tool that enables you to watch how posts get shared on Google+. If you publish user assistance or support information via Google+, it could help you track how far and wide it gets distributed. It could also help you see who are the most influential people, when it comes to transmitting a message.

Anthologize

Anthologize is a free, WordPress plugin that enables you to publish the content as electronic texts.

Grab posts from your WordPress blog, import feeds from external sites, or create new content directly within Anthologize. Then outline, order, and edit your work, crafting it into a single volume for export in several formats, including—in this release—PDF, ePUB, TEI.

Writing user documentation collaboratively in an Agile environment

Hi,

You provide wonderful newsletters full of useful information. Thank you.

I’m a Senior Technical Writer in a small company, and I have one contractor working for me. We have come up against a challenge. <snip>… My team currently uses RoboHelp, which is not a collaborative, team tool for writing. The company likes to think the product addresses this issue, but they really do not.

I have searched for a writer-friendly product that allows collaborative, team writing on a project. Unfortunately, I haven’t found anything. What product do you recommend for teams working on projects together? Right now we have to share files, meaning only one of us can work on the project at any given time. This is a serious issue for us since we are in an Agile development environment where we support twelve developers. More will be added soon, but we there are no plans to bring on more writers.

TS

How would you advise TS?

What does a Help Authoring Tool give you over Drupal?

Comparing Help Authoring Tools (HATs) with Drupal is like comparing apples with oranges.

HATs are used by Technical Authors to create content in various formats for end users to read. Drupal is open-source software that is used to create websites for users such that they can contribute to the content (for example: blogs, personal or corporate websites, e-commerce sites and intranets).

That said, if you are a HAT user and then have to work in Drupal, it is useful to be forewarned of the main differences. The top 3 things that a HAT user will miss when starting to use Drupal:

1. The most frustrating thing about using Drupal, having come from a HAT background, is having no summary list of pages (topics) available in a different frame.

As an Administrator in Drupal, you can view a list of pages, but you can only edit the properties of one page at a time. There is no multiple-selecting and no drag-and-dropping. So topic management can be very labourious.

2. Out of the box, there is no way of managing links. So, for example:

  • If you delete a page then all links pointing to it will break, and there are no messages to warn you.
  • When creating a link in a page you have to know the path and name of the destination page – there are no helpful lists of available pages.

There are modules you can install, which can help. The “Links” module is the most complete on paper but, in Drupal 6, it can cause a programming error (i.e. not an error in the way I installed it).

3. Out of the box there is no WYSIWYG editor. For the majority of HAT users this is a must. You can only write your content in full/filtered html.

I highly recommend installing the “Wysiwyg” module. This module makes it much easier to install WYSIWYG editors. Some of these are less successful than others. If you are interested in keeping your underling code clean (i.e. free from unnecessary <span> tags created by inline styling), I recommend the “TinyMCE” editor.