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.

By this point we have completed analysis of our content (looked at a few sample chapters and identified the main types of content that we have), we know the problems we face now and in the future (lack of intelligent structure, no re-use of content, slow turnaround, and limitations around the tooling) and what we need to do to fix them (rewrite/repurpose the information appropriately). We know the tool we are going to use (Author-it) and are confident it is a best fit to our needs. Which leaves one further question.

When do we start this work?

Which is where we are now. We have the tool, and I’ve just set up our content database. Next up we are looking to pull together some high-level scenarios for how our product is used so we can match those to the new structure for the documentation. Yes, that’s right, we are also considering restructuring the documentation. Well, why not, we’re having to chunk and import the information so may as well get the output structure correct as well.

The scenarios should also help us decide what content to migrate first as there is little value in migrating content that doesn’t need to be updated or re-used. The idea of using scenarios came from one of the team and the more I think about it, the better a fit to our needs it will be as it should allow us to build better documents and help systems, as well as focus the migration process on the areas of highest priority.

Ultimately it may turn out that we never migrate some areas of our legacy content. The only reason would be to reduce the reliance on an ageing toolset but even then it will be a decision of cost.

As with most projects of this type, where you have a long timescale, there are other concerns we need to take into account which include rebranding the company and a push (which I’m involved with) in getting a company wide information strategy in place. A lot of that will drive other work as we are aiming at gaining better consistency of information and messaging across all the areas of our company which is yet another reason why our single source solution will be a great asset to the company as a whole.

The current plan is for the rest of the team to work on new information purely in Author-it, whilst we create Content Plans to make sure we migrate the correct information in time for the next release. To allow the team to continue to work I’ll be handling all of the migration so, probably some time next week, all work in FrameMaker will stop and we’ll take a ‘cut’ of the documentation which will, from that point onwards, be our main stream of work.

The Content Plans should allow us to rebuild the documents we need, slotting in the new work that the team have been working on… seamlessly… I hope!

Fingers crossed, the countdown has started.

One part of the agenda for our day long “Author-it day” was to consider how we would handle multiple streams (versions) of documentation.

As well as major versions of the documents (3.x) that continue to move forward, we also keep up with changes to maintenance releases (3.x.x). The overhead isn’t too bad, we rarely have to make changes for a maintenance release, but we do need to have the capability to do so and this is where we hit a stumbling block.

Author-it offers the ability to version an object (a book or topic for example). You can have multiple versions of an object but only one can be active. So, originally, our thinking was to create the first (in Author-it) version of each Book and then use the basic “1-up” versioning provided by Author-it.

However, when running through a quick demo of such a system, it became apparent that whilst that model works for major releases (X.x) when you consider the occasional maintenance release (X.x.x) then, very soon, your folders become cluttered with a myriad of versions of objects, none of which are easily identifiable to a particular product version.

So, our solution will be to duplicate objects (copy) to a new version specific folder.

We are switching to Author-it just in time for a new major version of the product line. This allows us to import ALL our existing content as 3.0. From that point onwards each major version will kick off with the duplication of all the Book objects (remember, a book is just a collation of topics for output). Then any topics that change, or are added, for that version will be duplicated (copied) and moved to the new version folder.

Clunky? A little. Manual? Completely. But it’s the only way we can manage our versioning process without ending up with a mess of versioned objects.

Unless, of course, we’ve missed something very obvious.

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.

With a most recent product release almost out of the door, our thoughts turn to the next few months and, finally, beginning to move our content to Author-it. During our weekly team meetings, and across several shorter planning meetings in the past months, we’ve covered most of what we think we need to have covered.

However, to be sure we’ve decided to have an entire day, locked away in a room, to go over the basics and properly plan the content migration. We have a provisional agenda but it’ll be a fairly open session for most of the time, as long as we can drive out actions I’ll be happy. I’ll be shifting my PC into a meeting room and running it on a large screen so we can actually try things out whilst we are there.

So far the agenda looks something like this:

• recap the basics - what is reuse, what topic types do we have
• EXERCISE - take a sample chapter and walk thru the import method
• where will the imported topics live? (we have a structure, is it right?)
• how do we handle maintenance of different versions of the guides?
• EXERCISE - working practice - RID needs changed from 2.7 through to latest - how do we do that?
• output templates - what do we need?
• working with graphics - agree best practice
• what import templates need to be created
• who will import what?

The two exercises are there to help us troubleshoot any potential issues that may arise in everyday usage. We’ve already had discussions around topic types, the structure of the content within Author-it and I think we’ve covered everything but the main underlying aim of this day will be to flush out anything we’ve missed, or highlight any minor niggles that we aren’t aware of yet. Hopefully we can answer all of our questions (or at least understand the questions properly) and move forward from there.

Of course the REALLY big question is whether I bring in doughnuts or chocolate biscuits for the day…

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.

Where should it live?

Next up in our journey towards Author-it nirvana is to decide how to store our content. Author-it stores information as topics, and as topics are designed to be reused, locating them is a key part of the Author-it solution.

One approach would be to simply dump a lot of the topics in loosely appropriate folders and let the built-in search help us find the topics we need. That way the topic names can be a little ambiguous as the content of the topic is what matters.

However that feels a little like flying by the seat of our pants so I’m keen to try and figure out the best way to store the content within Author-it not only to make it easier for the technical writers, but to future proof us as much as possible.

The Author-it Knowledge Center (sic) is chock full of useful information and includes a topic on folder structure which rightly states that:

You need to choose the approach that best suits your requirements. You can have as many folders as you need (but remember that too many, may get confusing…) and as many levels as are required. Also consider the reusability of your content. By burying objects in a myriad of sub folders, others may not know that these objects exist and end up creating multiple copies of the same information - meaning the information is duplicated in more than one place.

Another useful thing to know when creating folders is that when folders are created, they inherit the security of its parent. Therefore, when you design your initial folder structure, it is worthwhile creating some folders at the very top level to set security, and then creating any sub folders within these.

One thing my team and I are hoping to adopt is a DITA based structure. Whilst built in DITA support is not yet part of Author-it (but it’s coming) we do like the way DITA approaches topic-based writing and can easily map most of our content to the default topic types with which DITA is concerned. This also gives us an exit route out of Author-it should we ever decide to change our tooling in the coming years.

However, simply storing all of our content in 3 or 4 folders (1 per topic type) would still leave us with a huge number of topics per folder, so obviously we need some other way of structuring the content logically. And, in a nice twist, we are also going to be restructuring how we offer the published content in the future so we can’t base the folder structure on our current documentation set. That makes sense moving forward as well as we may well start offer different groupings of information anyway and I’d rather not perpetuate our current document-centric view.

So, what have we decided?

After some thought we realised that the only way to structure the content in Author-it to make it easy to locate is to focus on user role. We discounted using product terms here as some of the information we will be writing in the future doesn’t easily fall into a specific area of the product so we’d end up with a generic “Other Stuff” area which suggests that that was the wrong approach.

Essentially we have three user types for our product set; Developer, Administrator and End User. Under those folders we then break down the information accordingly into areas of product information (for example “Installation”). We tried to steer away, again, from using product specific areas but as the large part of our product is a development kit we realised that it made sense to base that information on the “tools” within the development kit, rather than trying to conceptualise the information any further.

Beneath those folders we then break out into, loosely, DITA-focused folders of Concepts, Procedures, and References, with an additional folder to hold Graphics (screenshots, diagrams and so on). DITA suggests Tasks, not Procedures but we consider a task to be at a higher-level, with one task containing one or more procedures.

So we have a basic folder structure in Author-it that looks a little like this:

\Administrator [User Role]
	\Installation [Information Area]
		\Concepts [Topic Type]
		\Graphics
		\Procedures [Topic Type]
		\Reference [Topic Type]

We think this will work for us, and we’ll be testing it with a sample chapter or two very soon. We definitely need to get this right now before we start converting our content over but the thoughts and details of that exercise are for another post.

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.