I’ve mentioned DITA a few times on this blog, and my DITA is not the answer post is still attracting attention. As I’ve said, I think the DITA standard is an excellent one for software documentation and the DITA movement is slowly catching up to the hype. I’ve never given up on DITA and had always planned to use it as the basis for the next stage of our content development, and as it happens the switch to a full DITA/CMS based solution may be closer than I had anticipated.

We have been considering how best to publish up to date information in keeping with patches and minor releases, and if we can tidy up and publish useful information from our internal Wikis and support system. The nature of the product we work with means there are a lot of different usage patterns, not all of which we would document as they fall outwith typical (common) usage.

So, how to publish formal product documentation, in-line with three versions of the product, in PDF for ‘printed’ manuals, JavaHelp to be added to our product, and HTML to be published to a live website alongside other technical content (ideally maintained in the same system as the product documentation). Storing the content as XML chunks also allows us to further re-use the content programmatically (which can be tied into our product in a smarter, dynamic, fashion).

The obvious answer is single source using DITA to structure the content, storing the content as XML to give us the greatest potential avenues for re-use. Nothing particularly startling there I know, but it’s a switch from the direction we had been considering. So I’ve been catching up on what’s new in DITA-land and have to admit I’m a little disappointed.

We already have FrameMaker and Webworks in-house, although both are a couple of versions old, and thinking we might keep using those applications I’ve been hunting about to see if I can find a solution that offers a coherent, end-to-end, story. There are several CMS solutions which require an editor, editing solutions which require a CMS, and a few products that straddle both CMS and editing but then require publishing engines.

I understand that it would take a collaboration between vendors to be able to offer a simple, seamless solution

In addition to that there does seem to be a tendency for any DITA focused solution to remain the remit of the overly technical. Don’t get me wrong, I’m quite happy delving into XML code, hacking elements, or running command line scripts to get things done. But surely I shouldn’t have to resort such things? Now, I’m sure there are many vendors who will tell me that I don’t need to worry, but I’ve seen several demos and all of them miss a part of the FULL story.

Come on then vendors, stick your necks out. If you are a CMS provider, then recommend an editor. If you sell editing software then talk nice to a CMS vendor and start promoting each other (yeah Adobe, I’m looking at you!).

And yes, I’ll happily admit that maybe I’m just not looking closely enough. If only there was some sort of technical community website that I could join, perhaps with a group or two on DITA? That’d be great.

Ohhh wait. There is! (not the most subtle plug in the world, was it? I think the new Content Wrangler communities could be a big hit, do check them out).

Have a got the wrong end of the stick, are there really gaps in the market in this area at present or is it just my imagination? I guess I’ll be running a fair few evaluations over the coming few weeks and, of course, I’ll post my thoughts and findings here.

If you are working in an Agile environment, and don’t have “single source” in mind when you write then you are slowing yourself down.

Working in an Extreme Programming environment (an Agile methodology that our Development Group follows) brings a unique set of challenges. During the early stages of a release, we spend a couple of days thinking about what we will be building, writing out the requirements as customer-focussed stories and breaking down those stories into discrete, small, chunks of work each of which has an estimated time for completion.

We don’t have a project plan, and as we work in tight iterations with functionality being released on a regular basis, there is always the chance that the scope will change at some point, generally with little warning. The system is built to deal with this so it’s not as bad as it sounds but it does throw up some challenges for the technical writer.

However with a little thought and awareness it’s a very easy system to work within, but does mean we need to push into other areas a little more.

First up you need to get involved when the developers are writing up the stories. Sit in the customer meetings and any planning meetings. Be the user advocate. Ask questions now. Stories are written from the perspective of the customer (with that customer being the person who requested the functionality) and you can (should!) help to craft these properly, making sure each story remains customer and real-world focussed. Every story, regardless of the functionality that will eventually support it, is a high-level requirement and should be stated as such. The actual work might be to make an object persistent, but the story will only say “The customer wants to be able to view previous transactions for each account”.

You should also be present during the break down of the work. At this point, with each story being broken down into small chunks of work for the development team, you can gain a better understanding of the functionality, including any presumptions and dependencies that may be added. Each piece of work should be no longer than a few days, less is better, and you can start to build an idea of the scope of work during these discussions. As yet I’ve not found any direct corrolation between X days of development work to Y days of documentation work.

So, from the stories, you should have a good idea of the high-level functionality that is being produced, and you can create an outline of the documentation that is required. You should also, having sat in on the discussions, understand the requirements of the customer and the reasoning as to why a certain piece of functionality is, or isn’t, being developed.

The chunks of work can help to feed into each section in your outline, and working to the same principles as the development group, you can estimate each section. Even if the figures are never published, it’s a good idea to take a stab at guess-timating the work based on what you know, allowing scope for research and playing with the software. These guess-timates also re-enforce the fact that you will be working on discrete chunks of work at a time, which should help you cope for descoping of functionality by the development team.

The speed of change is what makes Agile development so popular. If Agile development is the speedboat, the more traditional development approaches are most definitely the oil tanker. Slow to get moving, and hard to stop if a change of direction is needed. Understanding how the work breaks down, and writing in a style that helps encourage and support that, you should be writing discrete chunks of information that can be used anywhere.

In other words, you should be writing as if you are in a single source environment, even you don’t have a database or CMS in place, even if all that content is being held in one document. The principles and structure that single source systems promote will allow you to keep pace with development.

Be the speedboat!

What of agile documentation?

It seems like such an old argument that surely, SURELY, doesn’t need revisiting? Alas it seems that the world of software engineering still contains those who think that code = product. Thankfully, in my experience, the numbers are thinning as most practitioners of modern software practices are at least educationally aware of the need for product documentation, even if they don’t fully understand the reasons. However, there are still those who are happy to hack away, and then claim they have a product. If you are such a person let me make one thing clear, you are wrong.

Not only are you wrong but as time marches on, you get further and further from being correct, all the while creating further problems for you and your product.

Just over a year ago, in preparation for my new job, I spent sometime reading up on Agile development and in particular I focussed on Extreme Programming (XP). The more I read the more I came to realise that this was an area which was popular with developers, yet had little to no mention of product documentation as a fundamental part of the methodology.

Mention of unit and acceptance testing as fundamental parts of working in XP suggested there was at least an understanding of the importance of solid, well constructed tests to help make to a “better” application (test-driven development) but the more I read, the more I become slightly disconcerted at the lack of consideration given both to the production of product (end user) documentation or of the benefits and skills a technical writer can bring to a development team.

Truth be told, I’ve still to find more than a passing reference in any of the more recent publications and articles I’ve found but I’m happy to be proven wrong. Perhaps I’ve been reading the wrong things, and visiting the wrong websites? Or, more worryingly, perhaps there really isn’t anything out there.

Obviously, as a technical writer, the role of product documentation as part of the product is something that is at the forefront of my mind, and I’m not expecting any software engineer to have to worry about such things beyond understanding that we are a fundamental part of the product offering and hopefully agreeing that there is a level of expectation setting to be undertaken.

That said, I do expect a software engineer to understand that software without any support, be it formal documentation, training, or a dedicated support team, is NOT a product. If we can’t agree that fundamental trait then perhaps that problem requires a solution (thankfully, as I said earlier, I don’t think it’s a huge issue at present).

Quite simply, products include documentation, support and training, and tell a cohesive story to a potential buyer. A story that says, yes this product will do X, Y and Z, and if it breaks we’ll do our best to help fix it, and we’ll support you as you learn to use it throughout the lifetime of your relationship with the product (and, therefore, the company).

Admittedly the lines are blurring, with better UI design there is less need for the end user to head to the documentation for assistance but I’d argue that, conversely, as UI design improves and more people become aware of the basic principles of software applications (we all know cut and paste by now, right?) then the end users will start to stretch the applications in ways that hadn’t been considered and it is at this point that product documentation (information) becomes the key differentiator between products.

Of course it is possible to happily exist as a technical writer in an Agile world, but I think we need our voice to be louder.

So I guess my question is, who is willing to shout?

Note: I am aware of Agile Documentation, but I’ve yet to read it. It seems to be more focussed on a developer writing documentation though? I’ll post a review of the book soon.

“There is no such thing as too much information”

We’ve all heard this statement at one time or another, and in the internet age it’s accepted as a statement of truth. Which is shame as it’s completely wrong. Turns out, that you only need enough information, not all of it.

A while ago I wrote up some thoughts on how to integrate an authoring team into an Extreme Programming (Agile) development group. The post Trickle vs Traditional outlined a basic way of building up the required content throughout the various stages of an XP release and, to save you re-reading that post, let me grab the crux of what I was saying:

The trickle method relies on the ability of the technical author to retain a “big picture” view whilst working on multiple chunks of information at any one time. The information will not come in a set order, nor from a definitive source, instead it will trickle in from various parts of the development team, testing, and so on. Your job is to monitor the flows of information, position yourself within a stream (or two) and divert the information you need into the documentation.

In reality this means that you need to develop a good technique for filtering information, knowing when and what to leave out of the documentation and relying on your knowledge of the product to help you make decisions and make them quickly.

Quite simply, to remain agile in such a system you need to be able to make decisions. A decision can be wrong, as long as you make the decision to fix it as soon as possible.

In a way, you start to write by instinct, trusting that you properly understand all the myriad of factors that influence what information you are creating and letting your talents as a technical writer take over. As Malcolm Gladwell, who wrote an entire book about this type of decision making, suggests:

We live in a society dedicated to the idea that we’re always better off gathering as much information and spending as much time as possible in deliberation. As children, this lesson is drummed into us again and again: haste makes waste, look before you leap, stop and think. But I don’t think this is true. There are lots of situations–particularly at times of high pressure and stress–when haste does not make waste, when our snap judgments and first impressions offer a much better means of making sense of the world. [source]

All of that sounds slightly scary if you are currently working in a process-heavy environment, with requirements and specification documents been seen as a way to provide all the information everyone needs, and which are typically a rather slow cumbersome way of handling information.

Anyone who has written such a document knows how hard they are to do as you can’t know everything at the start of a project and over time things change. Having previously worked in ISO regulated companies, where the audit history of a document was almost more important than the information in the document itself, I know how onerous, time-consuming and false those systems can end up being. Many is the time when everyone in a discussion knows what is going on but you still have to write it up, review and approve it, before it can be officially logged in a system that is rarely referenced.

Monitoring the flow of information, trickling it into your documentation as and when needed, making quick decisions and trusting your instincts certainly feels like a more natural way to work. It does mean that there is no such thing as a final document and there is a chance you will publish something that is wrong; yet it is the very possibility of that happening which keeps itself in check. Allowing people to make their own decisions instills a higher level of professionalism and lowers the number of errors.

It’s not suitable for everyone and some industries wouldn’t enter it but it’s an interesting way to work. Limiting the amount of information you have available, and making decisions based on those seems wrong but it does work. You just need to be brave.

Can’t recall where I saw this but it struck a chord so I grabbed the main tenets with a view to expounding on them at a later date.

However, as simplicity suggests, I really don’t need to bother.

• Because there is complexity in purity.
• Elegance in plainness.
• Intricacy in streamlining.
• Richness in reduction.
• Depth in minimalism.
• Surprise in uniformity.
• Innovation in re-use.
• Cool in the avoidance of cool.
• And there is true sophistication in simplicity.

These were not written about Technical Communications but they might as well have been. I’m seriously considering printing these off and pinning them up on the wall.

Recently, Tom suggested that:
if someone can figure out how to make help whallop the user with wonder and awe, it will be the creative innovation of the century. Once we begin to establish a standard and a precedence, people’s beliefs will change from feeling that “all help is useless and unimportant” to “the help at my company is exceptionally good and useful; I will explore it more often.”

And I completely agree.

But.

Whilst he goes on to list ways in which the future of online help may expand - personalized help, feedback options, audiovisual options and such like - I think that is only one side of the coin.

While, without a doubt I could work harder to improve the content offered as online help, I think technical communicators need to expand their view a little, step back and see a bigger picture. I’ve touched on this before, and it is by no means original, but ultimately we are at a point where it is beginning to be realised that the information provided with a product is a most valuable commodity. With that in mind, the time is ripe for what Tom suggests, a new way of presenting information is surely on the cards. However I think it’s wrong to limit it to online help or documentation alone.

I’m lucky that, presently, I’m part of a company that allows the Publications Team (MUST change that name!) to be part of the softare design process. As such I can see, from inception to release, the decisions and design thoughts that go into producing our software, and I influence them as much as I can. Making the on-screen text useful is one thing, the next step is to think “task task task” during any discussions on design. Developers, rightly, take a requirement and start thinking about how THEY can implement it, yet just by repeating the “task task task” mantra I was able to get them to start thinking about how it should end up, rather than the finite possibilities of how it could be implemented.

Just to clarify, I don’t sit at my desk and chant. Instead I tend to start discussions about our software with “OK, I’m [insert user type], what am I trying to do here?”.

I’m not ramming this down anyone’s throat, but my choice of language during discussions has started to rub off, resulting in some design decisions made because they were thinking about the task the user is trying to complete, not the fact that it would need to get info from database A and publish it to form B.

In response to Tom’s post, I said:

Perhaps the radical shift is helping to address issues without presuming that people will “end up in the help”. Instead of being the last resort we should be striving to stop people having to get to that point.

That said, if they do end up in the help then yes, it should have a sufficient “wow” factor without being useless. Ultimately, make sure the information they want is findable by whatever means they choose.

Being the customer respresentative, the interface to the interface, is part of that.

I once told a Technical Support Manager that, ultimately, the aim for my team was to put his out of a job. Obviously that will never happen as the myriad of platforms, hardware, and user issues that surround every software product couldn’t ever be documented (unless development of the software had ceased, in which case I wouldn’t be working for the company).

I guess the aim for a usability team, or anyone interested in improving the user experience, is to put the documentation team out of a job. If the interface is well enough designed that the user doesn’t get stuck, and if it includes enough information in the UI to help the user make decisions, then why would they ever need documentation? Of course, similarly to the Support team scenario, documentation will be required to support the less travelled paths through the UI, to help the user who wants to do things her own way.

And that is where Tom’s suggestions come in. If we can improve the information we provide, making sure the customer experience is maintained (bettered?), then they are more likely to come back.

Single sourcing is good, I’m sure most of us can agree on that, but I’ve recently been wondering if perhaps DITA isn’t quite good enough?

The thing is, I’ve been looking at DITA as a solution for our single sources needs for a while now. I’ve attended conferences, read whitepapers, listened to vendors and everything else that goes with it and I’ve got a pretty good handle on things. If applied correctly the benefits you can gain are very large, although the same can be said of any other single source project, yet what seems to be consistently missing during all of these wonderfully theoretical discussions is the cost and impact of getting such a solution “applied correctly”.

A key part of planning to move to single source, of which DITA is only a part, is understanding the business needs and technological requirements of all of the content producers in your organisation. Traditionally that means Technical Communications, Training, Pre-Sales and Marketing, with perhaps other flavours to be considered depending on how your company is structured.

However, if those parts of your organisation aren’t yet ready to move, then the business case changes. At present this is the situation I’m in, so I find myself looking for a short-term (2-3 year) solution that won’t lock us in to a proprietary format and that can give us benefits as soon as possible.

Re-use is our main reason for moving to single source. We don’t (yet) localise, and there is only one other team that has any interest in re-using our content (and even then, they are likely to use it as an source of verification, not a source of content). With that in mind, and with the proviso that I’ve used it previously, we are looking at AuthorIT.

Yes it does mean we forego a lot of the power of DITA but as it will allow us to tag topics accordingly (in keeping with the DITA model) and it does have an XML DITA output option, then it shouldn’t lock us in. I’m willing to put up with a little pain further down the road to get the benefits now.

I’m still not entirely sure what else we are missing. We publish PDFs, HTML and Javahelp, all of which AuthorIT handles, and as yet we don’t have a need to dynamically publish information based on metadata. If that changes in the near future then we’ll handle it appropriately but it isn’t on anyone’s radar.

I am concerned about the versioning capabilities of AuthorIT as we maintain the last 3 versions of all our publications, but I know there are ways to achieve this in AuthorIT. I doubt it will work as well as our current system (FrameMaker files in an SVN repository) but, as is always the case, I do expect we may need to make some compromises to get ourselves moving towards single sourcing our publications. This is our main pain point and so becomes the focus for any possible solution.

DITA remains the long-term goal but, and I’ve said this before, until there is an all in one solution that is easy to rollout it remains marginalised as a viable option. Most of us need to produce some form of business case to justify such purchases and, at present, DITA is still too costly an option. I’m always happy to learn new things, and whilst I would love to be able to invest time and resource into creating and maintaining a DITA based solution, I just can’t justify it.

All of my research suggests that, rather than being a simple installation and conversion process, creating a DITA solution requires a lot of technical know-how and a not insubstantial amount of time and resource. We can handle the first, the latter is (I believe) not yet at a level which makes it cost-effective.

Ultimately, for the moment, DITA costs too much.

Do you agree? Can you prove me wrong? I’d love to hear your thoughts on this, particularly if you have implemented DITA already. I’m keen to hear just how more productive a DITA solution can be if you aren’t involved in localisation. Have you recouped your costs yet?

Perhaps DITA is only really applicable for those with large budgets and the chance to invest heavily upfront. Alas I’m not in such a position. For the moment.