Big plans take time

I’m procrastinating. I’ve reached a certain point in the work I’m doing that requires the completion of a very large planning spreadsheet. I’m currently looking at all of our content with a view to restructuring it to fit better with the way our customers work hopefully making it easier for people to browse the content. I’m taking an organic approach for this first pass. Taking the chapters in each current guide and rather than forcing them into a pre-existing structure, I’m making an educated guess as to where they might live in the future. Once that is complete I’ll take the list of suggested locations, give them a quick sanity check and mockup some examples and take them to some …

Continue reading

Hacking Author-it Webhelp

Finding the right solution for a problem isn’t always easy but sometimes, if you are very lucky, the solution will fall straight into your lap. Such was the case with our switch to Author-it even though we didn’t fully realise it at the time. I’ve covered our reasons for switching from FrameMaker to Author-it elsewhere, and once we had converted our content we started to look at how we could get the most from the other output formats available. We already had ideas on how we could use the provided HTML based publishing formats to provide a better solution to the problem of finding information, and we were planning on generate HTML versions of the entire documentation set to be …

Continue reading

Analyse this

Let me tell you a story. In it our hero (me) fights valiantly against two Javascript dragons called Webhelp and Google Analytics. It’s a bloody battle and at the end, when all the fighting is done, well … you’ll have to read on and find out. Some background first. We have a developer community website which hosts downloads of our software and all the documentation in PDF format. To make it easier for people to find information in the product documentation, we also host a Webhelp version of each and every document in one master Webhelp system so you can search across the entire thing. It works really well. To track how the other areas of the website are used, …

Continue reading

Access is good

Yesterday we launched a new version of our developer community website. It doesn’t have many ‘community’ features as yet but that’s all to come. One thing it does now have is an HTML version of all of our product documentation, in an easily searchable format. It’s no coincidence that it looks very much like the Author-it Knowledge Center as it too was built using Author-it (alas I can’t show you our website as it requires a login). This new format of the product documentation is largely to move us away from PDF only documentation. At present we still have a set of PDFs but they aren’t particularly usable. We ran a few quiet trials of the knowledge centre format and …

Continue reading

Dumping the manual

I honestly can’t remember the last time I picked up a user manual, an honest-to-god paper book of technical documentation. Actually that’s a lie, it was just last week when i was tidying up. I picked up several user manuals and moved them to a lower shelf on my bookcase. It’s also been a long time since I last worked for a company that produce and printed user manuals but that’s more to do with my career path than any decisions I made within those companies. Even now whilst we have a “documentation set” comprising several different user manuals, it’s published to PDF and made available as part of the product distribution (and also online). So why do we still …

Continue reading

Author-it Web Help Configuration Wizard

For version 5.3, Author-it released new web help templates and having played with them a bit I have to say I like them. However I was struggling to see how to enable some of the options that you can see in the example Author-it provide, so off into the HTML and CSS files I headed to see if I could see anything useful in there. And there is, several of the options are commented out in the HTML code and with a little bit of poking and prodding I got some of them to work. Pretty straightforward, if you know HTML and CSS that is. But what if you don’t? Well the good news is that the ever productive Hamish …

Continue reading

Author-it Hints, Tips, & Useful Info

The following are not in any particular order. Some are tips gleaned from experience, some are links to the knowledge being shared by others, all have helped us get us from a standing start to a full content conversion and production delivery in under 4 months. We started with ~2450 topics of imported content, and managed to keep pace with the development team as well as cleanup and backfill the imported content. Quite a feat! Working with Author-it As we were converting a LOT of content from FrameMaker to Author-it, there was a LOT of cleanup required. Being able to customise the styles toolbar, adding in the most common used paragraph styles for example, was a huge bonus. We ended …

Continue reading

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 …

Continue reading

Recently Read

With the TICAD conference last week, a couple of days in my sick bed, and the imminent product release I’m working towards, I’ve not had a lot of time to post here. However, the RSS feeds keep trickling in, so here are a few items that caught my eye over the past couple of weeks. What Beautiful HTML Code Looks Like I’m a terrible coder. Which is just as well because I’m not a developer but as I do dabble in HTML and CSS quite frequently (hey, and PHP too), then this is a good reminder for me to develop my own best practises. Code is Tabbed into Sections: If each section of code is tabbed in once, the structure …

Continue reading

Spanning the divide

I’ve been chasing this train of thought for a while now and decided to start writing my thoughts down in the vague hope that they come together in a way that makes sense to others. It seems to make sense to me but, as yet, there are a few grey areas into which I may stumble. So, not so much a train of thought but a car crash of ideas, if you will. Shoddy metaphors aside, the main crux of my thinking is based in my efforts to find a central point around which I can arrange my knowledge. Obviously my knowledge of some areas is greater than my knowledge of others, but part of this exercise is to start …

Continue reading