The tool is not important. The tool is not important. The tool is not important.

I have been repeating this mantra in my head for the past week or so, over and over, like a broken record. I’m in the middle of pulling together the requirements and scope for a new technical community website for our users, which will become the key focus of our technical information. The more traditional product documentation set will be maintained as we move forward, so there is some thought to be given towards how we manage the information as well as how it is published, or rather where.

I must stop considering the how. The tool is not important.

At present I have a list of requirements, all of which I’m thinking through from the point of view of how the process will work as far as creating and maintaining the information. Who will be access the source, who will be viewing the published information, who can edit what, how will the information be used by the audience? All the while there is a part of my brain dragging me towards HOW this will work. What tool will be able to handle our requirements?

The tool is not important.

I enjoy a challenge, and this is most certainly a new venture for me, but the basic foundations of this idea are rooted in things I know well, single sourcing content, developing online communities (I run a website for Scottish Bloggers (currently dead after our hosting service disappeared)). As such I’m confident I can get this off the ground, but even so I’m being careful to properly gather requirements, and fully understand the impact of changing our publishing model. Note I said “model”.

The tool is not important.

So with a list of requirements, and a full understanding of the processes that will be involved both to maintain the main documentation set and the development of other supporting information (culled from internal Wikis, mailing lists and anywhere else we stumble across something useful) one change is the way in which we plan, design and write product documentation.

As I’ve said, this is all about the processes that support the way we work. I’m being quite deliberate in how I pull together the requirements, focussing discussions on the audience, the expectations, the information and processes, with no mention of the technology which will need to support the new website.

The tool is not important.

Last year’s X-Pubs conference drilled this message home, and it’s good to be able to draw on the information and knowledge gained there. Get your requirements sorted out and agreed, understand the impact of changing the way people access information, and the impact of changing how people work, figure out how best to handle the reaction to change and agree the expectations and limitations of your system. Decide which models you will follow, how the processes will hang together and outline the various roles that will be required, and make sure they understand what is required of them.

Then and only then should you consider what tools you require and make sure they are serving you.

As I mentioned before, we are planning to migrate content from FrameMaker to AuthorIT, staging the migration across two different product sets (and no small amount of time!). I’m in the process of evaluating AuthorIT for, despite having used it before, it has recently been overhauled with a spiffy new UI and some new features.

AuthorIT is a single source system, with content stored in a central database, which can publish to most (all?) of the formats that anyone would ever need. It includes an editor, supports multiple users, and has some additional add-ons for localisation and so on. Their website is very good if you want more information on their product.

After downloading and installing the trial version, which limits your import and publishing but otherwise has all the features available for use, I fired it up and was greeted with the new interface. Based on the ribbons used in the latest version of Microsoft Office, it is quite a shift away from the previous version and it took me a while to get to grips with. However it is a huge improvement over the old version and once you are used to it, like anything, it’s very nice to use. Yes I know there are still issues being dealt with, but I didn’t run across that many during my testing, so I’m happy.

During my evaluation I spoke to their Business Development Manager who was very helpful in delving into some of the issues I had around versioning and set my mind at rest. I’ll outline how we are going to handle maintaining multiple versions of documents in another post, once I’ve given it a dry run or two.

One issue that cropped up was the location and format of the supporting database. You can run AuthorIT on a Jet database either locally or on a network drive although that is particularly performant, or run it on a SQL Server. As we are a small team I did consider the Jet database but our situation suggests a server database would be better. Which introduced another problem, price. SQL Server isn’t the cheapest and we don’t have an installation in-house. Thankfully one of our IT guys suggested SQL Express (a limited free version of SQL Server) as a possibility, and after a quick check on the AuthorIT Yahoo Group, I’ve found that it will run quite happily on that database.

There is a limit of 4GB on the database size but as long as we keep our images elsewhere there is little chance we’ll hit that limit. Our total content at present, including images, tops out under 500MB for one version of the documentation. So we’ll actually be saving space on a server as we won’t be maintaining multiple versions of entire documents. Must remember to point that out to our IT guys!

Aside from versioning the only feature I was unfamiliar with was the batch runner, which allows you to run a batch file (.bat) as a scheduled task. Our current system runs at night, using Webworks to create a Javahelp file which is then included in the software build and AuthorIT will give us similar functionality.

Why AuthorIT? Well, quite simply it gives us what we need.

I spent some time at the X-Pubs conference last year, and throughout the presentations the underlying message was “get your requirements sorted before hunting for a system”. The premise is obvious enough, if you decide on a system first, you end up shoe-horning your processes around how it works rather than getting a system that works you way YOU work.

I also spent some time considering DITA but ultimately switching to an XML-based system is still too cost-prohibitive. AuthorIT is a compromise, allowing us to work how we want to work, whilst giving us single source benefits. We will use DITA as a framework for how we plan and write the content, but the simple fact is that AuthorIT is a much better value proposition than a bespoke system, both in monetary and resource terms. This makes the business case much easier to sell.

If you are considering single sourcing your content, then I’d strongly suggest you investigate AuthorIT as a possibility. It has limitations, including the oft-cited reliance on Word as a publishing engine, but for me the advantages outweight those.

And no, I am not being paid to endorse AuthorIT.

Working with text, and graphics, can be a time consuming job. If you are like me you’ll know many keyboard shortcuts, some of which will be used repeatedly throughout your working day.

For example:

• CTRL+C
• ALT+TAB
• CTRL+V

Go on, who can hit that oft repeated key combination without even looking at the keyboard (you touch-typists can shush).

Cut and paste is so frequently used that it is often overlooked, yet it does warrant some thinking. I’ve tried adapting the way I work in the past but it turns out that I use a variety of different tools for a variety of different, yet very similar, tasks and the tool chosen largely depends on my mood.

I sometimes take text from an email into a Word document, sometimes I’ll start in Notepad (Notepad2 actually) and go from there, and other times I’ll just be moving things from one place to another in a FrameMaker document. The process is the same, cut and paste, cut and paste.

The flaw comes when you need to multiple items in multiple locations, leaving you flicking between windows and trying to remember what you last CUT so you PASTE the correct thing… how many times has that gone wrong for you?

Clipboard managers, as such pieces of software are known, have been around for a while, but I’ve never managed to work one into my workflow. Typically they are only need now and again but as that is the case how do they know WHEN they are needed, and when not?

I think I’ve found the answer, and it goes by the name of ClipX (yeah, the title of the post was a bit of a giveaway). It is a light-weight, unobtrusive clipboard manager that, with a little tweak to the default settings, makes it very easy to have the ability to go back through the previously copied items, without getting in the road of the more regular, one-to-one copy/paste activities.

If you download and install the application, you need to change one of the Popup settings. Right-click the icon in the system notification area, select Configure and then, on the left of the Configuration dialog, select Popup. Change the Default item setting to Last clipboard and you are good to go. I’ve also turned off the search and limited the number of items.

The really smart thing about ClipX is that it also handles graphics. I’ve been doing some web design work recently, hacking away and creating some basic graphics for the site. This is what my current CTRL+V action looks like (hitting Enter pastes the selected item, with the top-most, or most recent, item selected by default):

Smart, isn’t it.

Admittedly my infatuation with this little application may be because I’ve finally adjust the way I work to accomodate such a tool, but I like to think it’s also because it is an application that takes something simple and makes it work.

Single sourcing is good, I’m sure most of us can agree on that, but I’ve recently been wondering if perhaps DITA isn’t quite good enough?

The thing is, I’ve been looking at DITA as a solution for our single sources needs for a while now. I’ve attended conferences, read whitepapers, listened to vendors and everything else that goes with it and I’ve got a pretty good handle on things. If applied correctly the benefits you can gain are very large, although the same can be said of any other single source project, yet what seems to be consistently missing during all of these wonderfully theoretical discussions is the cost and impact of getting such a solution “applied correctly”.

A key part of planning to move to single source, of which DITA is only a part, is understanding the business needs and technological requirements of all of the content producers in your organisation. Traditionally that means Technical Communications, Training, Pre-Sales and Marketing, with perhaps other flavours to be considered depending on how your company is structured.

However, if those parts of your organisation aren’t yet ready to move, then the business case changes. At present this is the situation I’m in, so I find myself looking for a short-term (2-3 year) solution that won’t lock us in to a proprietary format and that can give us benefits as soon as possible.

Re-use is our main reason for moving to single source. We don’t (yet) localise, and there is only one other team that has any interest in re-using our content (and even then, they are likely to use it as an source of verification, not a source of content). With that in mind, and with the proviso that I’ve used it previously, we are looking at AuthorIT.

Yes it does mean we forego a lot of the power of DITA but as it will allow us to tag topics accordingly (in keeping with the DITA model) and it does have an XML DITA output option, then it shouldn’t lock us in. I’m willing to put up with a little pain further down the road to get the benefits now.

I’m still not entirely sure what else we are missing. We publish PDFs, HTML and Javahelp, all of which AuthorIT handles, and as yet we don’t have a need to dynamically publish information based on metadata. If that changes in the near future then we’ll handle it appropriately but it isn’t on anyone’s radar.

I am concerned about the versioning capabilities of AuthorIT as we maintain the last 3 versions of all our publications, but I know there are ways to achieve this in AuthorIT. I doubt it will work as well as our current system (FrameMaker files in an SVN repository) but, as is always the case, I do expect we may need to make some compromises to get ourselves moving towards single sourcing our publications. This is our main pain point and so becomes the focus for any possible solution.

DITA remains the long-term goal but, and I’ve said this before, until there is an all in one solution that is easy to rollout it remains marginalised as a viable option. Most of us need to produce some form of business case to justify such purchases and, at present, DITA is still too costly an option. I’m always happy to learn new things, and whilst I would love to be able to invest time and resource into creating and maintaining a DITA based solution, I just can’t justify it.

All of my research suggests that, rather than being a simple installation and conversion process, creating a DITA solution requires a lot of technical know-how and a not insubstantial amount of time and resource. We can handle the first, the latter is (I believe) not yet at a level which makes it cost-effective.

Ultimately, for the moment, DITA costs too much.

Do you agree? Can you prove me wrong? I’d love to hear your thoughts on this, particularly if you have implemented DITA already. I’m keen to hear just how more productive a DITA solution can be if you aren’t involved in localisation. Have you recouped your costs yet?

Perhaps DITA is only really applicable for those with large budgets and the chance to invest heavily upfront. Alas I’m not in such a position. For the moment.

Just in case you’ve missed these, TechSmith are giving away free versions of their software. Admittedly they are older versions but you can upgrade them for less than the full price of the newer versions.

Obviously they are hoping people will try them and like them enough to pay for the latest version:

• Get SnagIt 7.25
• Get Camtasia Studio 3

TechSmith have another product, which will capture images and video as well; Jing is available for both Windows and OSX, but it seems to be primarily aimed at sharing the content online.

What I’d really like is Skitch for the PC.

As I mentioned previously, the opening presentation at TICAD was by Adobe and featured their vision of the future of Technical Communications and information development. Apparently that future includes video.

Video has been available to many for a few years now, yet it is never really the main focus of a documentation team. Tom has questioned this as well:

“For too long I’ve minimized the importance of the audiovisual. Captivate — the industry standard tool for creating screen demos — is actually a relatively simple application. Mastering it and integrating audiovisual into user help will take it to the next level.”

This echoes what Adobe suggest, no big surprise there, but I have to admit that I don’t fully agree.

As a quick learning tool, I’m sure videos (screen demos) are useful, but I wouldn’t really know as I’ve never used one as a primary source for learning about a product and I’m not sure I know anyone who has. Of course that’s not to say they don’t have value and with some research into the intended audience I’m sure it can be proven that they have a valid place in the product documentation set.

However my initial thoughts on the matter are hard to shake.

It may be one of the unwritten rules of documentation, the rules that few people question and may well be inaccurately applied, but I’ve always operated under the assumption that people only use the documentation when they are stuck.

Of course this is a broad sweeping statement but I believe that it is true for the majority of software users. So, if that is the case, what is their mindset when they finally give in (having asked a co-worker and searched Google to no avail) and fire up the online help or open the user guide? Typically they will be annoyed and want an answer or fix pretty damn sharpish.

Why, in that case, would they even consider sitting through a 2 minute video that explains how to use the functionality with which they are currently battling?

To be fair, Tom isn’t suggesting this approach but I think it’s wise to counsel against this trend lest it be used too heavily. A few short demos of how to complete core tasks, accompanied by a comprehensive help system or user guide is the best balance.

My fear is that the “cool” effect will override sensibilities and we’ll be plagued by popup videos and worse in the future.

The written word certainly isn’t the only way to effectively communicate information, and as technology progresses we will all need to carefully match the available delivery mechanisms with the information we need to deliver. The key word here is “carefully”.

I’d love to hear from anyone who is already doing something like this, I’ve not used Captivate, nor offered any form of video as part of a documentation set before as they didn’t match the audience profile but I’d be interested in hearing how successful they were.

Make my living writing software documentation. There is, of course, much more to it than that, but that remains the bulk of the job. I also write as a hobby, both on this blog and on my other more personal blog. I also maintain a third website although that has been somewhat neglected recently (note to self: get the finger out!).

Suffice to say I write a lot.

In addition to that I have also adopted what is increasingly known as ‘web worker’ tendencies. As I work with, and on, computers it is simple enough to switch between different tasks, and the web is a key part of that working practise.

And the key part of that practise, for me, is Google Docs. The ability to import and export to Word, to easily maintain the content in relevant folders, and of course the ability to access and edit the content from any PC… well it’s almost a no-brainer.

But one thing that I’ve recently found useful, is the ability to share the documents, allowing others to view and edit them. Admittedly it was only between two people, but if you have a small team, or are working on a project that spans the globe (something that is increasingly common these days) then it’s worth having a look at Google Docs.