Tag: Author-it

Coming soon…

As we approach the end of our migration from FrameMaker 7 to Author-it, I’m going to try and pull together some lessons learned, some tips, and useful links that I’ve found along the way. I’m not claiming to be an expert (I’ll leave that to Rhonda Bracey and Char James Tanny, amongst others!) but, as they say, a problem shared is a problem that you might just find via a Google search… or something like that…

Pre-empting this, I thought I’d open things up to anyone who might have any questions about the process we’ve gone through. So, if you want to know my thoughts on migrating content (how NOT to do it, perhaps?) or anything specific to Author-it then leave me a comment.

Over to you!

Helter Skelter

Helter Skelter

When I get to the bottom
I go back to the top of the slide
Where I stop and turn
and I go for a ride
Till I get to the bottom and I see you again!!!!

Ever get that feeling that you’ve been here before?

I write this blog post with haste as I’m halfway through the penultimate week of a particularly arduous project. Not only are we releasing a new version of the product, but we are completing the first major stage of our move to Author-it.

Overall the migration has been pretty painless. There are still some Word templates issues to work around and getting to grips with Variants has still to be tackled, but overall we are pretty happy with our choice. The only major gripe we have is partly our (ok, MY) own fault, and it’s here that I’ll offer the most valuable tip I can.

If you are migrating legacy content to Author-it (we were moving from Structured FrameMaker), make sure you thoroughly test and check the import settings. Time constraints had me rush this stage and we ended up paying for it, spending far too long cleaning up rogue topics than we had planned. Every cloud has a silver lining though, and it does mean that the documentation is now far more consistently written and styled than it had been. However, going through some 5000 odd topics by hand wasn’t the greatest use of our time!

Soon we will be looking to how we can leverage the output to provide better access to information, feeding into the developer community website we have already built, and improving how we deliver information alongwith our product set.

For the former we have taken some inspiration from the presentation by Rachel Potts and Brian Harris (Red Gate Software) at last years UA Conference, titled Delivering Help in a Support Portal. For our implementation the Publications team will take the lead, and it’ll be interesting to see where it takes us. Web 2.0, anyone?

We will also be looking to provide better online help by introducing Keystone Topics, as suggested by Matthew Ellison. Author-it should make these topics, which are the first topics the user lands on when they start the online help and which provide sensible links to common information (rather than just providing repurposed user manuals), very easy to build.

Two of the team will be in Cardiff for the conference this year so it’ll be interesting to see what we learn there and how we can really start to leverage Author-it in more and more powerful ways. I’m definitely keen to start innovating what we do and, in a few weeks time, we won’t have any further barriers to stop us.

Author-it Tidy Up

Firstly a quick thank you to everyone who has commented on the previous post. What a fantastic bunch you are, and as I mentioned in the comments, I’ll be using your first names and locations in an infographic for an upcoming presentation. Fame will be yours! (Note: fame not guaranteed)

In other news I’m deep in the trenches of 2000+ Author-it Topics, stepping through each one to clean up formatting, correct hyperlinks, set the correct template and so on. I’m working my way through all our old content, imported using the MIF Import. It’s not the most stimulating work but needs must.

On the way I’m fixing bits and bobs in both Author-it and the Word template that we’ll use to generate the PDFs of our documentation from. If nothing else the context switch is keeping me sane!

One annoyance is the fact that I’ve had to add a “Reset Numbering” paragraph style as without it you’ll find your numbered lists (that we use for procedures) roll on and on through your document. I’d have thought the Procedure Heading style would’ve been setup to handle this out of the box but, alas, not. So far it’s the weakest area for me, and I’d certainly love to see some more example templates, either provided by the company, or on a community submission basis.

I’ve also spent a fair bit of time dipping in and out of the Author-it Yahoo Group which is a fantastically helpful resource. Well worth joining if you are an Author-it user.

Right, best get back to it. Hoping to get that number below 2000 by the end of this week!

How to embed linked images in Word 2007

Using Author-it to produce Word documents is easy. The tricky bit is distributing them.

Without running any post publishing macros, the Word document that is generated will be using linked images. So everytime you need to distribute the document you’ll also need to remember to include the images as well.

I frequently forget this, hence why I’m posting this, so, if all else fails, I can at least search my own blog to find the solution. If you look at a document with linked images, you’ll see that the filesize for the document is quite small, and there will be a number of images in the same folder (although this works fine if your images are linked from another folder).

UPDATE: You can also do this automatically after publishing using an afterPublish Word macro, the Author-it Knowledge Centre has the details, thanks to Derek Tomes for pointing it out. Read on for the manual method.

You can quickly and easily convert linked images to embedded images in Word 2007. Here’s how:

  1. With your Word document open, click the Office button*, top-left of the window.
  2. Select Prepare > Edit Links to Files.
  3. Select and highlight the images you want to convert from the list.
  4. Select the option to Save picture in document.
  5. Click the Break Link button.
  6. Click Yes to confirm.

The links are removed, and the images are now embedded in your Word document. A quick check of the filesize of the Word document should show a marked increase and you can now distribute the Word document, and the Word document only, safe in the knowledge that the images are embedded.

When to migrate?

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.

Versioning in Author-it

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.

Planning the big move

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…

How do we structure our topics?

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]
    		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.

How do we move to single source?

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.

Why we are moving to single source

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.