I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here.

How? - how do we do it?

Once we’d agreed that single source would provide us with a good solution (it’s still not ideal, but nothing ever is..) the next question was “How?”.

Having followed the technologies in this area quite closely over the past few years my immediate thoughts went towards a DITA enabled solution. The basic topic types and methodologies fit well with an Agile environment so there would be fairly immediate benefits once we got the system up and running. We spent some time investigating our content and planning how best to leverage DITA to our advantage and once we were happy that it would meet our needs (with less over head than adopting DocBook) we looked at the technological challenges of adopting a DITA based system.

And that’s where we hit the biggest block. DITA is an excellent methodology but still lacks simple/cheap tooling support (it would take upwards of several thousand to fully implement a DITA solution, whereas a bespoke solution could cost considerably less). Other considerations (we have JavaHelp as our online help format) also came into play and, after some investigation of other XML based tools we decided to go with Author-it and base our working practices around the DITA methodology and topic types.

We did consider upgrading our legacy applications (FrameMaker and Webworks) and configuring them to give us a solution that would meet our needs but even the rough estimates for that work took us beyond the cost of our chosen solution.

One caveat to this is to note that I have used Author-it previously and, whilst it is not without its foibles (which application isn’t) it hits the sweet spot of functionality versus cost. None of the rest of the team have used it but that would be the same for any other new tool and was considered as an upside to keeping the FrameMaker + Webworks solution.

A second caveat is that I’m fully aware that, in due time the tool vendors will get on top of this problem (MadCap already seem to be ahead of the others in this area), but alas the timescales don’t suit us. Worst case scenario is that we ditch Author-it in a few years, export the content to DITA XML and import to a compatible tool that meets whatever needs we have at that time.

I’ve waffled on about single source and our plans for long enough so, as we are finally starting the process itself, I thought I’d capture some information as we go along. However, it’s probably good to set the scene, so I’ll cover that stuff first. Over time you’ll be able to see all the posts related to this work here.

Why? - why single source?

A quick summary of our current situation. We currently maintain (and add to) ~2000 pages of documentation. The same content is used for both the PDF manuals and the online help provided with the product (exactly the same, no restructuring). There are various levels of coverage (some good, some bad), we are embedded within an Agile development environment, limited publications resource. On top of that we have an aggressive release schedule and a two-tier product which includes a development kit and an application built by us using that development kit.

Whilst we have made good strides in improving how we work with the software developers - we have a technical writer embedded in each new feature team and the benefits are evident from both sides - we know we need to be focussing our efforts in the correct areas, and providing information in a structure and format that meets the needs of our audience. Luckily we have direct access to the largest section of the audience as they work for the company.

Better structured information is one of the requests, and to allow us to get the most of our current documentation we would need to reuse a lot of the content we have already, but it’s locked away in FrameMaker files, sometimes in the depths of a 100 page long chapter. What to do?

Ultimately we believe that the ability to reuse our content will make producing the content faster - the current documentation set is unwieldy and hard to search, a little digging reveals some duplication already exists - and make us much more flexible when it comes to providing useful sets of information for our audience/customer.

Eagle-eyed readers will have spotted that we already single source our documentation and online help from the same FrameMaker files, but as we don’t reconstruct the online help into something more intuitive and useful it is, essentially, an HTML rendition of the manual. Not ideal by any stretch of the imagination.

Where does the ‘documentation manager’ fit in an organisation?

As our company grows and we push ourselves to be better it is envitable that some people will end up in slightly different roles than they envisaged. Thankfully my current company isn’t too bogged down on job titles and org charts, preferring to make sure that roles and responsibilities are defined and allow people to get on with getting things done.

So, I currently find myself conducting a mini content audit, across most of the company, in an effort to find the big gaps that may or may not exist (ok, that definitely do as every company has them) and working with a couple of other people in different areas of the company to make it happen.

It’s a switch away from concentrating on writing and managing the product documentation but it is an area I’ve long since considered something that someone in my position SHOULD be driving forward.

This exercise has given me the opportunity to touch base with most other areas of the company, and it’s telling that very few have a full product view. In fact I’d say it’s fair to say that none of them have (and rightly so) and so I often find myself pointing out that documentA is already in progress by teamB, so teamX doesn’t need to do write their own.

It also means that, once we have finished the audit and written up the missing information, we should have a cohesive and complete story through all the various touching points our customers have with our company. It should make our offering easier to sell, easier to understand and back up the fact that our product is excellent and our staff are a bunch of smart people!

I have a double interest at play here though, as I also have a developer community which I need to feed far more regularly than I have been, so any content is ‘good content’ as far as they are concerned.

An interesting time which, once again, reminds me why I love this profession of ours, after all who else gets to stick their finger in so many pies.

Tom Johnson has had a look at the survey recently published by the HATT matrix website on help authoring and, by pulling in the results of some other surveys in the same area, has extrapolated some good conclusions from them.

He rightly points out that surveys need to be taken with a pinch of salt (he goes into the detail of why this is so), and that whilst the numbers involved would seem to be high enough it’s likely that the questions themselves need further consideration in future.

That said, there are two things I took from his post.

1. Know the problem before picking the tool
You may not be in the position to switch authoring tools, but if you are and you have investigated the market then please make sure that you are buying a tool that addresses the problems you have.

The presumption here is that if you have a legacy tool (like we currently do, FrameMaker 7.1) and it still works and meets your requirements then there is no good reason to upgrade. I’ve been victim of buying into the ‘keeping up’ frenzy that software manufacturers like to generate but once a product is reasonably mature it is likely it has most of the features you need already.

I’d offer Microsoft Word as an example here, I could probably still use Word 2.0 for the few documents I maintain in that format as the newer versions add functionality I don’t need (and which has ended up intruding on my workflow at times!).

The X-Pubs conference a couple of years ago had a common, if not publicised theme. Almost all of the presentations included the advice to figure out what problems you had, before deciding IF single sourcing (using XML as the base format) will help and that’s even before you consider the tools themselves.

2. DITA is still a theory
Whilst it is true that the number of people leveraging DITA for their content is rising, the numbers remain low.

Partly that will be due to the fact that few organisations/teams/people are in a position to quickly switch just because a new technology has come along, but and I’ve said this before (in fact I’ve said that I’ve said this before!) rollout of DITA remains harder than rolling out a bespoke authoring tool.

When costing an implementation of a new tool there are various factors and it’s very easy to see that you can get MadCap Flare up and running quickly, where as a DITA based solution takes investment in developing the environment. This is beginning to change but, as yet, the phrase ‘DITA support’ really only means that you can output to a DITA formatted XML file. The tools aren’t constructed around the DITA concepts, so you immediately lose a lot of the benefits that DITA can bring.

Until there is a tool that fully leverages DITA, building it into the workflow of using the tool, and helping the concepts become part of your daily working practice then it will continue to be a marginal player.

Which, in a way, is how it should be. DITA is not a tool, it is a technology and methodology. It is there to support the toolset and the writer. It’s just a shame that tool vendors continue to believe that THEIR format is best, refusing to budge from that position and shoe-horning ‘DITA-esque’ features into their software.

Anyway, the rest of the survey write up is interesting and worth a read but, as Tom says:

“I do love these surveys, though; if for no other reason than they give us something to talk about”

Due to product release pressures I’ve not had much time to look at the new version of Author-it, let alone get the SQL database setup so the rest of my team can get it installed and starting having a play.

Whilst we are getting some training organised, I’m confident that we are smart enough to figure out a lot of the basics ourselves (I’ve used Author-it before so can guide them a little) leaving the training for the harder things such as variants.

Having finally sourced space on a server my next task will be to setup the database on SQL Express. This is a cutdown version of Microsoft SQL Server, with much the same functionality but a maximum database size of 4GB. Some initial size estimates suggest we are WAY off that so I’m confident it’ll see us through the next few years worth of content creation.

Alongside this I’ve also been involved in what can only be described as a content audit across the company. I’m lucky that I have a colleague who is as keen as I am on making sure the right people have the right information, and that our information needs to be easy to find and maintain. She works in Product Marketing so there is a fair amount of crossover. At present we are mired in spreadsheet hell, but it’s starting to come together and, in the long run, I’m sure the various consumers of product information will start to see the benefits.

I do seem to moving away from being involved in new feature design work which I will miss, but for the meantime there is a bigger void that I’m aiming to fill with the ultimate aim of rounding out our product offering.

So, exciting times ahead and hopefully a lot of good lessons I can share with you.

Every company is unique. Every company has their own processes, their own documents and, of course, their own language. That language is part of the culture and if you don’t embrace the new language it’s likely that there will always be friction and, worse, misunderstanding in the future.

Take, for example, the process documents you work with. Regardless of industry there is usually some form of communication that contains the requirements of what you have been asked to build, and after that it is likely there will be a more detailed communication that outlines what it will take to meet those requirements.

Previous monikers for the former, that I’ve come across, include Market Requirement Document, Business Requirement Document, Request for Enhancement and so on. The latter I’ve seen referred to as Functional Specification, Software Requirement Specification and Build Plan.

Which means, culture/language wise, I’ve spent far too much time reading MRDs, RFEs, SRSs and so on.

But the key is that whilst most of these documents do, essentially, the same thing, I’ve happily switched my language to incorporate these new terms. It’s not a big switch but it’s a crucial one which helps me frame my work in the correct terms. These things are, by and large, considered a small deal by many, but getting the culture right and buying in to that culture is key to building a successful team.

We are nearing the end of a release cycle and will soon be starting the next set of workstreams and, excitingly, we’ve managed to push the involvement of the technical writers right up to the early design stages.

What does this mean?

Roughly speaking the process of creating the stories is one part of the scoping and planning stages of our development cycle. Each feature is broken down into a set of requirements, and those requirements are further broken down into one or more stories. The stories are then broken down into discrete work tasks (a few days work at maximum).

The stories are stated in terms of “the user would like to … ” and are used to help the developers understand what they need to do to meet the requirements. We are hoping that, by writing them, we can both be involved in the early design stages as well as gaining an early start on the product documentation. The stories will become the concepts for the documentation, and we can then flesh out the tasks and reference information as and when the development work is completed.

Be interesting to see how well it works, but hey it’s worth a try.