Tag: XML

bookmark_borderWhat do we want?

Posted on

At TCUK12 this year, I chatted with several people about authoring tools. Vendors, other technical writers, managers, I asked the same two questions, again and again.

What authoring application do you use, and why do you use it?

The answers were illuminating, interesting and always useful. There are many, many options out there, catering to many different needs, and all of them have a different set of strengths and weaknesses. Alas, no matter how hard I tried, regardless of how many ways I tried to bend our requirements, all of those conversations led me to the same conclusion.

No-one out there builds what we want so we may have to build it ourselves.

As part of improvements to our content, one of my team has led the charge to restructure our information. She has a passion for information architecture and devised a three pronged approach to our content. You can either navigate in by role, by product area or… by something else we haven’t yet decided upon.

We’ve audited the topics we have and applied some simple structuring decisions and it is looking good so far. The problem we will soon have is that we will need to build this new structure and make it usable by our customers.

What we would like is to be able to tag our topics, and use those tags to present a default structure to our information. The tags would also allow users to filter the topics they see and, either by addition or subtraction, create a unique set of information for their needs. Ultimately this would lead to personalisation of content in a basic form, but that could easily be enhanced to provide a smarter take on content for each user.

Alas it seems that, without doing a lot of customising of an XML (most likely DITA) based system we won’t get near that and even the products that get close require a compromise somewhere. Most of the time it would be, for the team of writers, a step back to a less friendly interface, and more exposure to the underlying technology of the tool they are using. At present Author-it provides a simple authoring environment that allows the writers to concentrate on writing content.

But perhaps that is the point. Maybe it’s time to try a different set of tools, adopt new working practices, take on a the bigger challenge.

bookmark_borderTagging

Posted on

Last night on Twitter I asked “Looking for a way to tag topics in an authoring platform. Not part of Author-it, does any app do it?” and a few helpful people gave me suggestions.

I later clarified and thought I’d expand on that here. My clarification was that “Re tagging: we want to tag topics in the authoring tool so whatever the output, the user can filter on tags eg, v1.0/email or v2.3/document”, it was at this point I realised I needed more than 140 characters to explain what I was looking for…

Our product is in the throes of moving to a modular/component delivery. We will no longer have one installer to install one big product with everything in it, instead you will likely (it’s still being figured out) get a core application which you can then enhance with additional modules.

The challenge to our team will be to document this product in a way that is useful to both the people who might use the application and to those people who customise the application for specific customer needs (which may or may not involve customising a module or creating a bespoke module for a customer).

One idea that may help us in this would be the ability to tag all of our content with module/component/functionality tags, and a version tag. There may be more tags required but we can figure those out later.

However, the authoring product we currently have, Author-it, doesn’t offer this functionality. We have looked into a way of manually doing it by hacking XML files but it’s less than ideal.

So what I was asking for, badly, on Twitter was a native application that includes tagging of topics on the authoring side, with the tags then available in the output. Ultimately we want to be able to build dynamic sets of information AND allow the users to change the view of the information based on the tag(s) they’ve chosen as well.

MadCap Flare comes closest as it at least has a notion of ‘tags’ in the product but not sure if that allows a dynamically built output, and Robohelp allows tagging of returned search results but no way of producing that content dynamically.

Does such a product exist? It  feels like it should, that it’s not a million miles away from what a lot of technical writing teams would want… but I don’t think it does. Prove me wrong!

bookmark_borderTechnology vs Emotion

Posted on

Random thought: Has the rise of (talk of) emotional content (affective assistance) been driven by the concentration, over the last few years, on technological solutions?

Single sourcing, XML, DITA, DocBook, and all the rest have (rightly) taken our profession forward, so I guess it’s natural that the general trends, as well as refocussing on the content itself, are looking for how to better engage with a modern audience.

The evidence suggests that that modern audience is Facebooking, Twittering, and blogging, and wants content in easily digestable chunks.

That plays nicely into the hands of single sourcing (chunks) and the idea of emotional content through connecting to the user, using friendly language to make the content easily digestable.

So, if you’ve already got your technology sorted out, why aren’t you looking at how your content is presented?

bookmark_borderConference Connections

Posted on

I’m still tweaking my presentation for the Technical Communications UK conference, Thursday morning is looming larger and larger in my view so I’m distracting myself with considering the other good things that happen at conferences.

For me people are the primary reason for attending a conference. Don’t get me wrong, the value can be measured by the quality of the speakers and the information provided, but that tends to be transitory, so it’s the connections you make that count in the longer term.

I’m lucky that I’ve met some of the people I know through this blog, and I’m hoping to add to that tally this week. Part of me did consider trying to organise a little “meetup” of bloggers in attendance but I think I’ll leave it down to fate, I’d hate to NOT meet someone because I was concentrating on one small part of the crowd.

At times attending industry conferences can be a bit of a guilty pleasure, it’s only after the first hour or so you realise that yes, you CAN make jokes about the kerning on the dinner menu, or laugh at yet another example of Microsoft Word being helpful. It’s also acceptable to spend your entire lunch discussing whether audience surveys are a good thing, and whether you actually need to learn XML or not.

Obviously the presentations will drive some of the topics of discussion, but (and admittedly this is usual over dinner and a small beverage or two) conversation with your peers can lead to all sorts of other things. Chess boxing being one memorable conversation from a couple of years ago at TICAD.

So, despite still not being quite sure what the final form my presentation will take (I may also adapt it on Wednesday evening to reflect back on the speakers of the day) and not being 100% sure how I’ll get from the airport to the hotel (bus? taxi?), I’m starting to get a bit excited.

There will be a blog post published here on Thursday morning to coincide with my presentation, and I’ve no doubt I, and several others, will Twitter our way through the conference.

If you see me at the conference (I’m kinda hoping at least one or two people turn up for my presentation!) then rest assured, as long as you have either a coffee or a Guinness in your hand for me, I’m very likely to welcome you with a big smile.

bookmark_borderDoes single sourcing content work?

Posted on

One of the more popular posts on this blog is titled DITA is not the answer and, whilst things are certainly moving forward, it’s a little sad that it is still valid.

A recent comment on that post suggested that it’s not just DITA that is lacking, it’s the working realities of single source that is flawed.

Well, that and the fact that I keep referring to single source when I am actually meaning content reuse (for you can have one source for everything but not reuse the content anywhere).

You can read the full comment yourself but the relevant bits are:

I have never seen single sourcing work. Maybe a single author who knows the topics thoroughly enough to reuse, or a tightly knit group of writers synched up at the same level.
…
The only place we are going to reuse content is in web mashups using semantic markup once the content is in the cloud.

It’s an interesting view and one which touches on something that has been on my mind these past couple of weeks as we are in mid-migration towards our single source solution.

Just how do you coordinate a team of writers, working in discrete areas of the documentation, with a large number (3000+) topics?

There are a number of ways we are tackling this and only time will tell if they are successful. Firstly we spent some time discussing how best to structure the source topics. Do we group them by product area? By topic type? Or some other arbitrary method?

We decided to group at the highest level (the top level folder) by user persona, and below that we grouped topics in accordance to how they are viewed from the product, so development kit wide ‘Events’ are stored in single folder, where as topics for a specific piece of functionality in the development kit are stored in their own folder. Your system will be different, of course, but this method suits our needs.

After that we need some way of knowing both what type of information a topic contains, as well as where that topic is used. We are not authoring in a DITA specific environment but decided to model our topic types on the DITA model to future proof us as much as possible (we are using Author-it which will export to DITA XML should we need it in the future). We have different templates for each type of topic (Concept, Procedure, Reference and so on), primarily to allow us to identify a topic (by default, Author-it shows which template a topic is using).

That leaves the final piece of our puzzle. How do know where a topic is used? This is more than just a list of which deliverables the topic will appear in, it also has to hint at the context of how the topic is being used.

Does any of this mean that we are more likely to reuse content? Not necessarily but it should give us a fighting chance, and once we’ve updated the content plans for all of our deliverables we will start to really see the benefits. Those content plans were the very things that suggested we could reuse content across multiple deliverables and I’m certain that, with a bit more analysis, we’ll get further gains.

Can single source and content reuse work? Of course it can. There are plenty of good examples out there and they all share one thing in common, something that isn’t really broadcast by the vendors; content reuse from a single source takes a lot of hard work.

But it is possible.

bookmark_borderHow do we move to single source?

Posted on

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.