As we are in the midst of rethinking our publishing processes, I’ve been looking at the current crop of tools, and (for our needs) three of them stand out over their competitors. Adobe, AuthorIT and MadCap seem to be heading for a battle royale, with the latter two the David to Adobe’s Goliath. But who will win?

Before yesterday I wouldn’t really have put MadCap in that battle but it’s been a busy time for MadCap, who (yesterday):

..unveiled its roadmap for the first complete, native XML software family designed to solve all of a company’s documentation and authoring demands. The MadCap family will include five new products: MadCap Blaze, MadCap Press, MadCap Team Server, MadCap X-Edit, and MadCap X-Edit Express, as well as enhanced versions of MadCap Analyzer, MadCap Flare, MadCap Lingo and MadCap Mimic. The tightly integrated MadCap family will provide companies with an end-to-end solution for developing and delivering content in print, online and on the Web—and in their language of choice.

[full details]

OK, so MadCap have a lot of ideas, but what does this mean for the technical communications industry? Putting aside discussion on bespoke solutions, in what state is the current crop of “out of the box” products? And, ultimately, why is this news from MadCap so intriguing?

Looking at the current tools the obvious and dominating product is FrameMaker. Recently updated by Adobe and with a new lease of life alongside Robohelp in their Technical Communication Suite, the future looks bright for the product and as the market leader it’s a safe decision to adopt their products and, like Microsoft in the OS business, it’s safe to assume they aren’t going anywhere anytime soon. With a little work and additional tools, the Technical Communication Suite offers a smart multi-publishing system built around well-known and well-proven tools.

Then there is AuthorIT, which has been on my radar for sometime now, and the latest version certainly offers more functionality and builds on their core strengths. Their entire suite covers a lot of the areas that MadCap are targetting and it’s already being used by technical communications departments. The latest version is, in essence, a 1.0 so has a few rough edges and issues but the AuthorIT camp are making the right noises and I expect it to become a solid and viable solution for many people wanting to move into multi-format publishing from a single source.

At this point I should really mention the other tools that make up the rest of the market but as I’ve not really been heavily involved with anything else (Arbortext, ForeHelp, HDK are about it) it would be wrong of me to summarise both their market share and their futures (if anyone else has an opinion here I’d love to hear it in the comments). I would guess that, and I include AuthorIT and MadCap in this, the rest of the market outside of Adobe is fairly evenly split across a variety of products.

The new MadCap offerings bulk out their current product set into a complete end to end publishing system and, from what I can see with the limited details on offer, ticks all the boxes. On the other hand, both Adobe and AuthorIT will say the same thing so perhaps we need to see a little more detail before we get too carried away?

Yet, despite the fact that the feature set MadCap announced has a bigger overlap with AuthorIT, the feel is that MadCap are aiming squarely at Adobe. Of course, it’s understandable that they are aiming at the biggest target as chipping away at the other players probably isn’t a sustainable business plan, so the question is whether or not they can beat Adobe at their own game.

Given that Adobe were missing in action for a few years, the speed at which they have ‘caught up’ has impressed me but having seen demos of both their Technical Communication Suite, and of MadCaps offering (before these new products were announced) my gut feel is that Adobe have only caught up and aren’t moving forwards as fast as MadCap. In fact I think it’s safe to say that MadCap, and AuthorIT, are changing the game and I’m not sure if Adobe are properly positioned to respond.

As Ellis, over on the Cherryleaf Blog suggests:

I still have concerns that Adobe still really doesn’t understand the practicalities of technical communication, that features appear as solutions looking for problems to solve. However, Adobe is the market leader and, as we’ve seen in IT many times before, it’s often the company with the best marketing (rather than the best software) that wins.

The latest swathe of products gives MadCap a full, end to end, system that should be able to handle anything a ‘typical’ technical communications team can throw at it. In saying that, without a little more detail it may all be smoke and mirrors (something they’ve been accused of in the past) but the simple fact is that MadCap have already demonstrated they ‘get’ the current marketplace, and they’ve certainly made a big enough splash to warrant the attention.

I wonder, if we fast forward a couple of years, if the marketplace will still have one big player. I suspect not as the noises coming out of both the MadCap and AuthorIT camps speak of big things, so perhaps Adobe need to look over their shoulder and up their game? Regardless, the main winner of this competition is you and I, the technical writers who deal with these products on a daily basis. As far as I’m concerned, the biggest part of the MadCap press release is the fact it exists at all. Challenge the status quo and things start to happen, quickly, and the technical communications community can only benefit.

I’ve mentioned DITA a few times on this blog, and my DITA is not the answer post is still attracting attention. As I’ve said, I think the DITA standard is an excellent one for software documentation and the DITA movement is slowly catching up to the hype. I’ve never given up on DITA and had always planned to use it as the basis for the next stage of our content development, and as it happens the switch to a full DITA/CMS based solution may be closer than I had anticipated.

We have been considering how best to publish up to date information in keeping with patches and minor releases, and if we can tidy up and publish useful information from our internal Wikis and support system. The nature of the product we work with means there are a lot of different usage patterns, not all of which we would document as they fall outwith typical (common) usage.

So, how to publish formal product documentation, in-line with three versions of the product, in PDF for ‘printed’ manuals, JavaHelp to be added to our product, and HTML to be published to a live website alongside other technical content (ideally maintained in the same system as the product documentation). Storing the content as XML chunks also allows us to further re-use the content programmatically (which can be tied into our product in a smarter, dynamic, fashion).

The obvious answer is single source using DITA to structure the content, storing the content as XML to give us the greatest potential avenues for re-use. Nothing particularly startling there I know, but it’s a switch from the direction we had been considering. So I’ve been catching up on what’s new in DITA-land and have to admit I’m a little disappointed.

We already have FrameMaker and Webworks in-house, although both are a couple of versions old, and thinking we might keep using those applications I’ve been hunting about to see if I can find a solution that offers a coherent, end-to-end, story. There are several CMS solutions which require an editor, editing solutions which require a CMS, and a few products that straddle both CMS and editing but then require publishing engines.

I understand that it would take a collaboration between vendors to be able to offer a simple, seamless solution

In addition to that there does seem to be a tendency for any DITA focused solution to remain the remit of the overly technical. Don’t get me wrong, I’m quite happy delving into XML code, hacking elements, or running command line scripts to get things done. But surely I shouldn’t have to resort such things? Now, I’m sure there are many vendors who will tell me that I don’t need to worry, but I’ve seen several demos and all of them miss a part of the FULL story.

Come on then vendors, stick your necks out. If you are a CMS provider, then recommend an editor. If you sell editing software then talk nice to a CMS vendor and start promoting each other (yeah Adobe, I’m looking at you!).

And yes, I’ll happily admit that maybe I’m just not looking closely enough. If only there was some sort of technical community website that I could join, perhaps with a group or two on DITA? That’d be great.

Ohhh wait. There is! (not the most subtle plug in the world, was it? I think the new Content Wrangler communities could be a big hit, do check them out).

Have a got the wrong end of the stick, are there really gaps in the market in this area at present or is it just my imagination? I guess I’ll be running a fair few evaluations over the coming few weeks and, of course, I’ll post my thoughts and findings here.

Recently I’ve been toying with some software tools to try and focus my writing a little better, stumbling across an application called Q10. A full-screen text editor which is, according to the website, “a simple but powerful text editor designed and built with writers in mind.”

Whenever I start a new piece of work I tend to write up notes in text files first, before moving them into FrameMaker for formatting and publishing. This was largely borne from limitations in Structured FrameMaker, and sits well with our usage of an internal Wiki for content collaboration. Q10 helps with this approach by doing one thing very well.

Like most well-designed products, the features are usable out of the box, but there is enough scope for tweaking things to get a system that suits you. The full-screen aspect of Q10 is the most important, blacking out the rest of the screen and leaving you with a blank slate on which to focus your thoughts. There is no menubar, with options only available through keyboard shortcuts, including one to turn off the typewriter noises which I’ve left on as they are somewhat soothing… oddly.

You can set the file encoding, a target number of words (handy if you are writing an article), change the font and colour settings, and it supports quick text allowing you to replace given character combinations with whatever you specify (I use this for product names, although you have to search and replace on the underlying text file if the name changes).

At first I was only really using Q10 for writing blog posts and articles, but I’ve started to extend it into my set of ‘work’ tools and it’s proving very useful. Sure it gets some odd looks as people glance at your screen but I certainly seem to be more capable of focusing on my writing these days.

I’ve tried a few other full-screen text editors (for Mac and Windows) but as the bulk of my writing time is spent on Windows machines, Q10 is proving very useful. Best of all it’s free!

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.