In this podcast I describe why Acrobat shared review is so good and why the closest things I could find (WebNotes and SharedCopy) just don't do what I'm looking for.

Links

• Acrobat Pro: http://www.adobe.com/products/acrobatpro.html
   
• WebNotes: http://www.webnotes.net/
  
• SharedCopy: http://sharedcopy.com/
  

This video shows how to configure and create a shared review in Acrobat Pro. Because it goes through the configuration steps for setting things up, it makes it all look much more time-consuming than it actually is. Once you've set this up, generating the shared review is simple. We used the same internal server approach demonstrated here (using a WebDav folder on the server) and it works really well for us.

Didn't have my camera with me, but I snapped these with my Blackberry:

View Full Album

Technical writers in a software development department often feel like third-class citizens, with programmers as the top-dogs and testers being granted second-class status. This engenders a certain camaraderie between fellow poor relations, testers and tech writers, filling, as they do, roles that are sometimes viewed as subordinate or auxiliary to the majority party within the development department. The work of testers and tech writers often starts at around the same time, and both roles can be subject to "ship early" pressure to keep the time available to them to a minimum.

But like tech writers, testers - rightly - believe that what they do is a crucial, if undervalued, function for the creation of quality software products.

Amongst other things, I ask Richard:

• What is software testing?
• Why do we need testers? (Can't programmers just test their own code?)
• What's the difference between: unit tests, integration tests, regression tests, functional tests, user acceptance tests, lean testing ...?
• How do testers and programmers get on? (Don't programmers get really irritated by testers finding bugs in software the programmer thought was working fine?)
• Why can't we introduce automated testing and save on all the money we're paying all those testers?
• Are technical writers as useful to testers as testers are to technical writers?
• Who'd be a tester?

Got any thoughts on the matter? Leave a comment below.

For something completely different, have a read of Richard's blog:
ROCKETBOOTKID AND BOOSTERBOY'S PALACE OF RIGHTEOUS JUSTICE.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

What does RSS stand for? Who invented it? What happened along the way? This podcast tells the story of RSS, from its earliest beginnings in 1995, through the births of XML, blogging and then podcasting, to the present day.

For the full script of this podcast, with lots of lovely pictures, look no further than: http://www.itauthor.com/2010/03/16/a-history-of-rss/
This page also has a full list of references for all the quotes and clips I used.

No sooner had I recorded this podcast than it was out of date. Right at the end I describe Tim Bray as leaving Sun Microsystems. He has since taken the position of "Developer Advocate" at Google. I also said that the last Daily Source Code appeared in February 2009. That was true at the time but yesterday Adam Curry resurrected it with DSC822.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

I ruminate over whether it's acceptable to use unscripted, unpolished screencasts in published documentation. Does it matter if you stumble over your words once or twice, um and ah, and have to correct your typing as you go along? Does the unscripted approach add an element of authenticity and make the whole thing more realistic and believable?

I also talk about the functionality I've been adding to our Madcap Flare projects to provide alternatives to the built-in glossary popups and expanding sections.

Finally I scan through my iPod and make a podcast recommendation. The podcast I chose was Speechification.
Website: http://speechification.com/
Podcast: http://feeds.feedburner.com/speechification 

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Matthew Ellison runs his own UK-based training and consulting company, specializing in user assistance design and technology. He coordinates the annual UA Europe Conference and is himself a popular speaker at conferences and training events around the world. He also regularly publishes articles and reviews on user assistance.

In this edition of the ITauthor Podcast I talk to Matthew about the UA Europe Conference.

We discuss:

• the number of countries from which delegates attend the conference
• what it’s like being the organiser of a large conference for technical communicators
• how can delegates justify the budget to attend the UA conference in these difficult economic times
• the sessions and speakers we can look forward to at this year's conference
• the No.1 issue affecting technical writers today
• trends or changes technical writers ought to be aware of
• what keeps Matthew busy when he’s not organising and running the UA Europe Conference

Talking about the “good enough” philosophy for user assistance, Matthew says:

"There's a fine line between doing documentation that's good enough and not being professional, and I certainly would never want to put something in front of a user that I didn't consider a professional piece of work."

Find out all about the UA Europe Conference at: http://www.uaconference.eu.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

This time round – recorded over Skype – Graham and I discuss:

• “technical author”, “technical writer” or “technical communicator”
• being forced out of technical writing by personal economics
• why contractors are more productive than permanent documentation staff
• an occasion where the tech writer was the closest thing to a Subject Matter Expert in an application development team
• tech writers being considered “the lowest of the low”
• why management find tech writers the easiest people to “let go”
• using voiceovers rather than written callouts in videos
• is documentation sometimes really remedial work on a bad user interface?
• what do we actually need to document in an online help system?
• being proud of the work we do

StoryCorps recording in this podcast

This episode of the podcast ends with a StoryCorps recording of Ed Miller talking to his son EJ. This audio was provided courtesy of StoryCorps. Please visit www.storycorps.org for more details and, if you like what they do, please consider making a donation to help keep the StoryCorps mobile units on the road.

The part of this recording that I really identified with was where he says:

We go to the mall nowadays, me and Mom, and I see dads walking with their sons or daughters, holding their hands, and I tell you, my heart aches for the days when I used to do that …

Podcast recommendations:

The Writing Show  –  http://www.writingshow.com/index.html 

(Graham refers to the recording I made for the Writing Show.)

The StoryCorps Podcast – http://www.storycorps.org/listen/podcast

Application recommendations:

Skype – http://www.skype.com

Techsmith Snagit – http://www.techsmith.com/screen-capture.asp 

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

This time round – recorded over Skype – Graham and I discuss:

• Migrating online help projects from RoboHelp to Madcap Flare
• How I use twitter and why Graham doesn’t
• Integration of social media – for example, information flowing from your blog to twitter to Facebook
• The death of blogging?
• Hard times for ITauthor’s stats
• Geoff Pullum, Geno Washington and the Ram Jam Band 

This is the photo I mentioned of Geoff Pullum (who was calling himself Jeff Wright – bottom left) with Geno Washington and other members of the Ram Jam Band.

I hadn’t realised, until scouting around the internet to find this picture, that Geno Washington and The Ram Jam Band had two of the biggest selling UK albums of the sixties. Hand Clappin, Foot Stompin, Funky Butt Live was in the album charts for 48 weeks during 1966 and was only out-sold by The Sound of Music and Bridge over Troubled Water.

Podcast recommendations:

Adam and Joe – http://www.bbc.co.uk/podcasts/series/adamandjoe/

Great Lives – http://www.bbc.co.uk/podcasts/series/greatlives/

Application recommendations:

WebEx iPhone application – http://www.webex.com/iphone/

Freemind – http://freemind.sourceforge.net/wiki/index.php/Main_Page 

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Professor Geoffrey Pullum, Professor of Linguistics at University of Edinburgh, recently wrote an article called ‘50 Years of Stupid Grammar Advice’ in the Chronicle of Higher Education on the 50th anniversary of the publication of Strunk and White’s Element of Style.

I visited Professor Pullum in his office in a beautiful new university building in the heart of Edinburgh to talk to him about his article and to discuss grammar and technical writing.

Among other things, we talk about:

• the split infinitive
• “none of us are” or “none of us is”?
• that and which
• the view of grammar as commandments brought down from the Grammar Mountain
• the pressure to enforce grammar rules, even when you don’t believe them
• why do most of us know so little about grammar?
• if we shouldn’t use Strunk & White, where should we go for grammar advice?
• nerdview

We also mentioned Professor Pullum’s talk at last year’s UA Conference Europe:
The Piranha Brothers, the Unwritten Grammatical Law, and the Phenomenon of Nerdview,
which is well worth reading if you find this interview interesting.

Related recordings:

• Professor Pullum on NPR’s Talk of the Nation phone-in, April 16, 2009
• Professor Pullum interviewed on NPR's Here and Now show from September 2006
• Marc Acito marks to 50th anniversary of Strunk & White’s Elements of Style on NPR, April 2006

Related blog posts:

• Happy Birthday, Strunk and White! – from the New York Times’ Room for Debate blog
• Pullum on Strunk and White from Orange Crate Art
• Hardly [adverb] convincing [adjective] from Orange Crate Art
• The End of Strunk from SLOG

Other links:

• Geoff Pullum’s Home Page
• Language Log

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

I thought about calling this “the heavy breathing episode” because there’s a lot of puffing and panting in this recording: the puffing from me, the panting from my Italian Spinone, Lottie, as she sprints and I plod up the Pentland hills a few miles from where I live in Edinburgh.

In this podcast I talk about:

• My decision to try commenting on other people’s blogs
• Using twitter
• Trying to get more done

One aspect of getting more done is trying to use my time more productively. So, to that end, I thought I’d use some dog walking time to record this podcast.

I suspect some (or all?) of you may find the rambling nature of this recording tedious, but hopefully you’ll enjoy the birdsong! Let me know what you think by dropping me a comment. If no one likes this style of on-the-hoof recording I’ll stick to the indoor type in future.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

What's the difference between a programmer and a software developer?

Why are there so many programming languages?

What's .NET ("dot net")?

In the first of two interviews with Technology Manager Colin Paterson, I try to get some answers to these and other questions about software development.

Look out for part 2 of this interview, coming along soon(ish) depending on Colin and I coordinating a free lunchtime.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

This time round, Graham and I discuss the best way of interviewing technical writers.

Skills/attributes we mention as being things we’d look for in a candidate for a technical writer position include:

1. Evidence of solid English language skills (particularly competency in written communication)

2. A genuine enthusiasm for technology (and preferably a fascination in software)

3. Signs that the candidate would fit into the team, provide effective peer review and would be able to interact with the developers

4. The ability to review the work of colleagues effectively – and to have your work reviewed

Podcast recommendations:

The Best of MySpace – http://www.bestofmyspace.uk.com/

Mostly Tunes – http://www.mostlytunes.com/

Note: The song I play at the end of this show is one I heard on a recent Mostly Tunes show:

Be OK by Ingrid Michaelson – played here by grace of the Podsafe Music Network.

Listen to more of Ingrid’s songs.

Application recommendations:

Adobe Buzzword – http://www.acrobat.com

Google Calendar – http://www.google.co.uk/intl/en/options/ 

Tips:

Press Q on Google Calendar for a quick, natural language way of adding an appointment.

What I’m listening to:

Graham is (still) listening to the music from the Transformers movie.

Oops! – a note about the sound quality

Despite a quarter century of podcasts (if you see what I mean) I still managed to make a couple of schoolboy errors with the recording of this podcast:

1. I didn’t check the levels properly, so Graham is too quite and my mic is maxing out

2. I accidentally recorded in mono. Usually I record with each mic into one side of a stereo recording so that I could remix the levels.

So apologies if I sound worse than usual in this recording and you’re struggling to hear Graham.   

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

In this podcast, I give a quick overview of the bid writing process, I describe some of the reasons why technical writers are an obvious choice to join a bid team and I give a few tips for surviving the bid writing process and submitting a completed bid on time.

Extract from the podcast:

As a technical writer asked, or told, to work on a bid, you may feel about it much the same way a developer feels when he's told he has to document the product or features he's just coded. You're naturally inclined to feel like this is not what you signed up for, and that there are lots of better, more important, more appropriate, more interesting things you should be doing.

However, I believe you should try not to feel like this, because it's an important job and it's one that you can probably do better than anyone else, so it's really a chance for you to shine. If you want to raise your profile within the company, you won't get a much better chance of doing so as a tech writer than working on a big contract-winning bid.

Tips:

1. If possible, don't tell people the submission date. If you let on it's a week on Friday, you might not get anything back for editing until a week on Thursday.

2. Get yourself organised. You need a system for tracking the progress of a large bid. Knowing exactly where you are with the bid, even if you're a little behind schedule, will help to keep the stress levels down.

3. Arrange little rewards for yourself and for everyone working on the bid. If you can make the job less of a chore you'll get better results. Bring in cakes when a major section is complete and make plans to go out for a night out the day the bid is submitted.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

In this podcast I explain why I think release notes are important. I talk about what customers expect to find in release notes. And I step through a typical release notes template.

Here's the text of this podcast:

I seem to have been spending a lot of time recently working on release notes. And because I haven’t written release notes for a few years I’ve had to think quite a lot about the purpose of them. Specifically: 

• What’s the point of them?
• How are they used?
• Who uses them?
• What do people need to get out of release notes?

All these questions have been buzzing around my head recently, so that’s the subject for this podcast: Release Notes.

Now you might be thinking that this isn’t relevant to you, and in your current job maybe it’s not, but believe me release notes are important in some positions and you never know, at some point, you may be looking for a position elsewhere, or you might want to work as a contract technical writer in which case, sooner or later, you’ll be working somewhere where you need to know about release notes.

The first thing I’ve realized is that, out of all the documentation I produce, the release notes are the only thing that I can guarantee will get read. And they’re not just read – they’re positively scrutinized in a way that most documentation isn’t, because it’s just there for when it’s needed and as long as the customer knows that it is there then that’s generally enough. So, for instance, the customer might have sign-off requirements that stipulate that they won’t accept the software (and pay for it) unless it has: online help, a user guide, an install guide and a configuration manual, or whatever. But they won’t read these through – they just want to check them off.

The release notes are another matter. When we release a new version of our software we want our existing customers to install it – maybe because it’s going to fix some issue they’ve been having, but maybe just because we can offer better support across all our customers if they’re all on the same release – at any rate we want to avoid too wide a range of releases being in use out there. And we really want to avoid customers sticking on an old release and not budging. So an important point to be aware of is that the release notes should spell out for the customer the incentive, or compelling reason, for upgrading. On the flip side, a lack of any incentive or compelling reason in the release notes may provide customers with their justification for not upgrading.

I mentioned before that release notes are read carefully. In all my years as a technical writer and documentation manager I’ve had very little spontaneous feedback from customers. Customers are usually happy to comment on the documentation if you ask them nicely and get them at the right moment. Face to face they’ll typically struggle to give you an immediate response because it’s probably something they really haven’t thought much about. This is a good sign. Documentation is like a referee at a football game, or the umpire in tennis. If you notice him it’s usually because he’s doing a bad job. So, typically, the person you ask for feedback will delegate the job to someone who uses the software more frequently and – in due course - you’ll get some comments back. But through all my years writing manuals and creating user assistance the No.1 subject for documentation-related comments from customers is the content of the release notes.

Where I work right now our standard release notes document has been largely shaped by one of our main customers. Again: this is a good thing. If you’ve got customers taking an interest in your products and telling you what they want then you’re lucky. They’re doing some of your work for you.

You’re initial reaction, when you get a customer saying: “We need rollback instructions” or “We need to know exactly which minor release versions of the such-and-such server-side software is compatible” – you’re initial reaction might be: “They’re trying to tell me how to do my job. I'm the technical writer. I don’t go telling them how to do their job.”

This is the wrong approach. This is like sending a document out for review and then taking umbrage because your reviewers actually picked you up on some of the things you wrote. Just because you didn’t ask your customers for their opinion doesn’t mean you shouldn’t be grateful to get it.

And whereas when you get review comments back, you take a view on which comments you’re going to act on and which of the suggested changes you’re going to make – with comments from customers, you better have a very good reason for not acting on them. If you take the view that you know better than your customers then you really need to stop and think about who’s paying your wages.

So, why do customers care about release notes?

Well, maybe your customers don’t. It really depends what sector you’re working in and what type of product you’re documenting, and how those products are sold.

In my case, our customers are generally large organizations running mission-critical systems. Our software is integrated into the customer’s enterprise-wide network and in many cases the software is operational 24/7, 365 days a year – so an upgrade to the software that may result in any downtime for the system is a big deal. Likewise there are training issues for any new functionality or changes to the interface. And there’s generally acceptance testing, where a sandboxed installation of the new release is tested before a decision is made whether or not to upgrade.

Of course your customers may not be so interested in release notes. For consumer products, for instance, your customers may never bother to look at the release notes – they may not know where to find them, or care less – they might not have a clue what release notes are. But the chances are that – even in this scenario - release notes do still exist, and someone needs them even if your customers generally don’t. In some organizations the release notes may be more for internal consumption than for external reading. Your support partners or MVPs probably want to see release notes and developers who have recently been moved into the product team for this product might want to read up on what’s been happening with the product recently.

Technical writers also find release notes very useful. Let’s imagine that the tech writing resource is short. Lots of developers churning out lots of code, day in day out, making lots of new product and changes to the existing products, and not enough people documenting all that new stuff. Imagine this state of affairs persists and a product has a series of releases where the core documentation (the Getting Started Guide, the online help, the admin manual) aren’t updated. You just didn’t have the staff to update that material. Nevertheless, when times get tight and you’re cutting back on everything that can be cut back on, the last thing you stop doing is writing release notes. If you release without release notes you may as well pack up and go home. But in fact you’ve probably gone already. You’re probably working somewhere else by that point.

Anyway, let’s suppose you’ve been prioritising products A, B and C – and, as a result, products X, Y and Z haven’t had any documentation done through a handful of releases other than the release notes. And then things ease off on A, B, C and you can spend some time on X, Y, Z. The first thing, as a technical writer, that you’d go to, to give you a good idea of what had not been documented through those releases would be the release notes.

All the new functionality and important changes will be listed in the release notes. So if you’re on release 7.5 now and the last update to the online help was done for release 7.2, you can pull up the release notes for 7.3 through 7.5 and, in double-quick time, you’ve got all the details you need to scope out the work you need to do to get the help system bang up to date again.

And believe me, when you pull up those release notes and you find they’ve been written thoroughly, and you can be confident that all the changes and new stuff did make it into the release notes, it's such a relief, because it can save you many, many hours – if not days –

of effort.

But this talk is really about the scenario I’m most familiar with, where your customers are large organizations or corporations for whom their IT system is a critical part of their operations. There are a range of reasons why release notes are important to such customers – but let’s just look at the three I touched on earlier:

1. They provide details on what’s involved in the upgrade process

2. They tell the customer what changes have been made to the software

3. They inform the customer’s testing regime

So, taking each of these in turn:

No.1 – What’s involved in upgrading the existing system?

They’ll be looking for an indication of the complexity of this task to give them an idea of any downtime that’ll be needed, whether data conversion is involved (which will play a large role in the

risk assessment they carry out for the upgrade). They need to figure out how many staff will be involved in performing the upgrade. They’ll need to cost the work and schedule it. The schedule will involve booking time from the appropriate people and working out the best time to carry out the work, allowing for the possibility of a problem occurring and having to back out of the upgrade.

For that reason they’ll expect the release notes to say something about installation (that is first-time installation), and more importantly upgrade (with details that specifically mention upgrading from the release they are currently running, so that they have confidence that the supplier has tested the upgrade path from their existing release to the current release).

And they’ll want to see roll-back instructions because they want to know that the supplier has thought about how the customer can get back to the existing version of the system if the upgrade to the new release fails.

This might sound like a lot of stuff but of course all of these things may be very simple. Chances are that installation or upgrade just involves taking a backup and then double-clicking an installer file, and rolling back might just be a case of moving the backup back into place. These things needn’t be complex, but they still need to be mentioned.

Typically, release notes have a standard set of sections and those sections appear in every set of release notes, even if there’s nothing to say. For example, you may have a New in this Release section, but it’s a minor bug fix release, so there’s nothing new. In that case you’d still have the New in this Release section, but it just says something like: “No new functionality has been added in this maintenance release.” Doesn’t sound great. But at least that way everyone’s clear.

However, sometimes the installation or upgrade process is complex. In this case these procedures may require a separate document (such as an Upgrade Guide or an Installation Guide, or both). Again, if your release notes normally have Upgrade and Installation sections, don’t leave these out because upgrade and installation are covered in separate documents. Keep the sections but just give them a one-liner pointing the reader to the other documents.

No.2 – What changes have been made to the software?

So the customer’s going to be looking for answers to the following questions:

• Have the issues I reported been fixed?
• What’s the scale of change?

  If there are significant changes, and particularly changes to the UI, or completely new areas of functionality then that’s going to impact my users and I may have to think about training – which means cost and inconvenience.

• Given what’s been fixed (or not fixed) – and the likely difficulty (or ease) of the upgrade, and any retraining requirements – on balance is it worth the trouble of upgrading?
• Do the list of changes indicate that the product being actively developed, or is the supplier just tinkering around the edges? In which case maybe I should be looking for an alternative solution.

This is the sort of information the release notes should be providing.

Point No.3 – What sort of acceptance testing needs to be done by the customer? 

So, assuming they haven’t (as a result of reading the release notes) changed their minds about upgrading, they’ll want to stick the software on a test environment and check it out. So they need to know what that environment should be (are there any changes there from the previous system?) and then, once it’s up and running, what do they test for?

Well the obvious things they’re going to test for are the new things: do they work as advertised and are they easy to use? And the fixed stuff: is it really fixed?

So, as a customer, I’d be hoping that the description of new features and fixed bugs was clear enough to allow me to try out those new features and at least spot-check the fixed bugs by trying to reproduce them. But if the bug’s not clearly described, there’s no way you’re going to be able to do that.

So I guess it's really all about giving the customer confidence. For IT managers in charge of enterprise-side software systems, new releases carry with them the fear of the unknown. If the current release is buggy they’ll be worried about the possibility of installing something that could have even more bugs. If the current release is nice and stable, and everything’s been running smoothly, then you could forgive them for adopting an attitude of: if it ain’t broke, don’t fix it.

The bottom line is you want to help them out. By the time they read the release notes they’ve agreed to upgrade (with various conditions) so you really want them to read your release notes and feel like they’re doing the right thing!

What about the format of release notes?

We produce our release notes as PDFs. We write the document in Microsoft Word and then generate the PDF after the Release Authorisation Meeting once the software has been signed off for release and the release notes have been checked and discussed in the meeting. Often the list of Known Issues in the release notes is pulled up on screen during this meeting and reviewed there and then in terms of:

• Are these the right issues to be declaring?
• Can we release with these bugs in the software?

We use Word for writing the release notes just because it’s not always the technical writers who write the release notes, so we have a Word template that anyone can use to write a set of release notes, and often reviewers want to mark their comments within the Word document (we don’t have Acrobat Professional - so people don’t have the ability to mark up or add comments to PDFs). But really I don’t think it matters so much what you use to write your release notes, or the format of the document you give to customers. A lot of companies use Web pages and that’s good – and it’s perhaps a way we’ll go in the future.

When I joined the company I work for now we used to send some release notes out as plain text files. And there’s nothing very wrong about that, except that a nicely formatted document is easier to read and looks much more professional. As I said before, the release notes are partly about inspiring confidence, and for me plain text release notes gives the impression this is bedroom coder software.

Publishing the release notes as Web pages and hosting them on your own Web site has the benefit that customers and staff always know where they are and can refer to them at any time. For example, when there’s a new release a customer might want to review the previous release notes particularly if they’ve missed some releases, and they want to reassess all the features and fixes in the releases they skipped as well as in the new release. It also shows prospective customers that you’ve got the balls to publish the release notes, complete with known issues, so it should help to show them that you’ve got nothing to hide.

Who writes the release notes?

I’m a technical writer, most people listening to this podcast are technical writers, so, guess what?

It’s often a technical writer who writes the release notes. But not always. Often the technical writer does an editing job on the release notes, and they’re actually written by the development project manager or lead developer. I’d say that’s’ the best way of doing things because the project manager knows what’s in this release, he or she knows what the keys themes of the release are, what the important resolved and unresolved issues are. And generally, the project manager has all the information that needs to go in the release notes.

I take every opportunity of reminding people where I work that no customer-facing documentation

should leave the building without it being edited by a technical writer. And, so often in the case, where the project manager, or senior developer, has written the first draft of the release notes, the technical writer gets to play the part of the customer - reading through the document and trying to think of what the typical customer will be looking for, or will need, from the document, and editing it accordingly.

But all too often, unfortunately, release comes along and the project manager has done nothing about the release notes, maybe they’ve dropped off the release checklist, or maybe the technical writer is just expected to produce the release notes. In this case:

• How do you start writing release notes?
• How do you find the information you need?
• How do you decide which issues to declare?

Well the starting point is typically the previous release notes document. Unless this is a new product, you’d typically pull up the previous document, rename it, and start editing it. Even for a new product I often start by pulling up the release notes for a similar product. We do have a template for release notes. But invariably, I find it easier to use an existing document as my starting point.

Finding the information to go in the document should also be very straightforward, with the project manager being your first port of call. He or she may not want to write the document but, as the project manager, they’re still the authority on the release, and they should know what they want to go in the document, or at least be able to give you the headline stuff and an overview of the type of other stuff you should be looking to put in there.

If you have a project management system, it should also provide you with a list of things that need to be included as new features or fixed bugs. The other main source of information will be your bug tracking system.

What do you put in there? What do you leave out?

These questions are particularly relevant for known issues (“bugs” to you and me) that either customers have reported, or which have been discovered in house, by QA engineers, technical writers, professional services staff and so on.

If you have a small piece of software that’s fairly new, and you have a small customer base, then the product manager might want everything to be declared in the release notes. But what about if you have a big, complex software solution that might have been around for years evolving steadily, or in leaps and bounds, through each release? In this situation you couldn’t possibly list all the bugs ever reported and not fixed, because the reality of software development is that there are always bugs and you never fix them all.

Some bugs simply aren’t worth fixing. You could put half a dozen developers to work fixing all the bugs, including the ones introduced as a result of fixes to other bugs, and they could spend months and months fixing those bugs, but from the customer’s point of view – the customer would see nothing happening to the product, release after release would come out with fixes to bugs the customer wasn’t bothered about, but no new functionality.

So what always happens is that bugs get prioritized. Bugs that damage data, or amount to security issues, or which prevent you using the product as intended get a high priority. Bugs that customers raise get a high priority, especially if it’s a big customer or a customer who’s about to buy something, or an influential customer who you need to keep happy. But there are always other bugs that get spotted in house, which occur rarely, in very specific conditions, or in remote corners of the application, and if these bugs don’t really inconvenience users, and nothing bad happens as a result of the bug, then this kind of bug will be given a low priority. And if there are other, higher priority bugs to fix and customer change requests to implement, then the low priority bugs may never be fixed.

Over the years these minor bugs inevitably mount up and if you list them all in the release notes then:

a) It’s misleading because it gives the impression the software is full of bugs, when in reality most customer would never find the vast majority of those bugs. It’s also misleading because it suggests you’re going to fix these bugs and in reality you’re not. Some of them will simply never be fixed. Because the business we’re in is all about bringing value to the customer, and there’s very little value for the customer in fixing those minor bugs at the expense of building in new functionality, or new products.

b) If you list all the bugs then it becomes difficult to see the important issues for the forest of minor ones. As I said before, customers generally want to check for the issues they’ve reported and they want to know about the risk of installing the software.

So, generally you should be declaring:

• All issues raised by customers.
• Any other high priority issues that customer need to know about.

The latter are the kind of thing you’d be embarrassed if your customers discovered and you hadn’t already found during QA testing. These are things that weren’t severe enough to prevent the software being released, but will definitely be fixed in a future release.

Rule of thumb should be that you never declare known issues in the release notes that will just sit in the known issues list for release after release and will never be fixed, because all the important bugs will be fixed and only the important bugs should be listed.

An eagle-eyed technical writer may have reported a spelling mistake in an error message,

but that shouldn’t take up space in the release notes.

And that leads to another point about the Known Issues list. The only way an issue can be removed from this list is if it is fixed. So issue 1201 gets listed as a Known Issue in the release notes for release 2.3.1. It’s not the highest priority issue, so release 2.3.2 comes along and the issue hasn’t been resolved, so it stays in the list. But after that it is fixed. So at release 2.3.3 it moves into the Issues Addressed (or Fixed in this Release) list. And then at 2.3.4 it disappears altogether.

This is a point you should bear in mind. If you put a low priority bug in the release notes, it might have to stay there for a long time, through numerous releases.

Who reviews the release notes?

So the release notes have been written. They’ve been edited. What happens next? Who reviews the release notes?

In my experience release notes are among the easier documents to get reviewed. People generally do care what’s in the release notes.

So apart from peer review by another technical writer, the release notes should be reviewed by:

• the product manager
• the development project manager or lead developer
• the release manager, if you have such a role
• at least one Support engineer
• at least one Professional Services representative
• the Customer Services manager responsible for delivering this release to customers

Practice where I work currently is that we try to get the release notes out to everyone at least a couple of days before the Release Authorisation Meeting, get the review comments back in, collate the comments, and get everyone a revised copy of the release notes before they attend the meeting.

Generally, there are some further changes raised during the meeting and these get implemented immediately after the meeting, after which the PDF is generated, gets a final check and sign off and is then shipped with the software.

The release notes template

So finally, it might be useful to describe a typical release notes document. Release notes vary, from product to product, with extra sections being added as necessary. But these are the standard sections in a release notes template:

Page 1: title page – Product name, document name (i.e. Release Notes), release number (e.g. Release 2.1), company name and address, contact numbers and web site address.

Page 2: title verso – publication date, copyright information and document version number (we have a code that tells us the names of the author and editor and the date the PDF was generated).

Page 3: Contents page

Then subsequent pages contain:

• Overview or Scope – This is simply a brief overview of what the document covers.
• System requirements – supported platforms (e.g. Windows XP with SP3, Vista with SP1, Red Hat Enterprise Linux 5, Solaris, whatever …), required third-party software (e.g. you might need to have Word 2003 or Adobe Acrobat 8 installed for some features to work)
• Features added – This is a description of all the brand new good stuff that’s gone into this release. This needs to be a functional, accurate description, but it also needs to be a bit of a marketing job to tell customer how this release improves the product – so you should describe the benefits of each new feature.
• Issues addressed – This is a list of fixed bugs (but we call them issues because “bug” is a techie word and “issues” sounds less like these are things we screwed up). In our case, we do this list as a table and each issue has the reference number our Support department gave the customer (this is a reference number for a case in the SalesForce system where we log customer information), plus we have the internal reference number from our bug-tracking system. The description of the issue is as brief as possible – just enough for the customer who reported the bug to be able to confirm that the reference number matches the problem they reported.
• Known issues – This is also a table with one row per issue – each issue having a customer ref, a Bugzilla ref and a description of the problem. The description should be as brief as possible and should give a context where appropriate – for example, if the issue only occurs when the moon is full and there’s a southerly wind, then you should include this information otherwise customers will assume the bug happens to all users all the time. Where possible you should include a workaround, but don’t include a contrived workaround for the sake of it – sometimes there just is no workaround and it’s annoying for customers if you treat them like idiots by suggesting a workaround that’s clearly not a real option for them.
• Installation – This is for customers who are new to the product. This section might just tell them to double-click the .exe file – or might refer them to a separate document if there’s a complex installation procedure.
• Upgrading – For customers who already use the product. Again this section might be very simple, but might involve some data conversion procedures, or it might include steps for backing up the existing installation prior to doing the upgrade.
• Rolling back to the previous release – What happens if you attempt an upgrade and it all goes horribly wrong – or you just don’t like the new version and decide to go back to the old system?
• Related documents – This is just a list of any other useful documents – for example, an installation guide, a configuration guide, admin guide, FAQs, or whatever.
• Release details – This is on the final page of the release notes and it’s just a little table containing a quick-glance summary of:

  – the application name

  – the release number

  – the build number

  – the build date

  – the supported database version (if this is client-side software).

Finally you might be required to include additional standard text in your release notes, such as:

• Disclaimers
• A copy of the GPL
• An anti-piracy warning and so on.

   

Top tips for producing release notes

Release Notes are often overlooked, or given to the junior technical writer to work on, but they’re a very important piece of documentation and worth getting right.

My top tips for producing release notes are:

1. Get the project manager (or lead developer) to write the release notes. If they don’t write, or at least draft, the release notes, you’re only going to have to pick their brains, so it’s much more efficient all round if they do the initial work, and you do an editorial job.
2. Use a template with standard sections.
3. Fix a procedure and get it agreed with all parties. Once you’ve done this you can use a checklist to make sure you cover all stages, include the appropriate information, and get the document reviewed by the right people.

I hope you’ve found this podcast useful. If I’ve left anything out, or if you disagree with what I’ve said, or if you have any questions, then please add a comment in the form below.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

On a recent StackOverflow podcast, a listener asked the presenters for tips on how to "get in the zone" as a programmer. We take up the theme here and talk about how you can get yourself in the writing zone as a technical writer, and we try to identify the things that prevent you from getting in the zone.

Preparation

Do adequate research up front so that by the time you you start writing you can continue writing without having to keep stopping to check things out because you know your subject.

Avoid distractions: Email

Resist reading your emails throughout the day, as they arrive. If you *do* read your emails, resist the temptation to act on them there and then. Make a note of things you need to do and come back to these things later.

Avoid distractions: The Internet

One Web page draws you to another and another and another, and before you know it half an hour has passed. Steel yourself to stay off the Internet. When you *do* need to visit a Web page, imagine you're back in the days of expensive metered dial-up, when using the Internet was a case of getting on there, getting was you needed as quickly as possible and getting off again. Just imagine you're paying from your own pay packet for each minute you spend on the Web during work hours.

Listen to the right kind of music

This one's a personal thing. I can mentally turn down the volume on conversations going on around me in the office, so that I'm not distracted from what I'm working on, until someone says my name a couple of times. But you might be the kind of person who finds that difficult and naturally can't help but listen to whatever chat is within earshot. If that's the case you might find it useful to put headphones on and listen to music. But it has to be the right kind of music. If you play songs you'll be listening to the lyrics. If you play music you really like, you'll be busy enjoying the music rather than writing. If you play mood music, you've got to make sure it's the right kind of mood: if it's too reflective or sombre it may bring you down. Graham recommends film scores (e.g. the music from the Transformers movie). I rarely listen to music while I'm trying to work because I tend to find the music gets top priority in my mind and I find time will pass and I suddenly realise I've just been listening and not working. One time the folks around me were chatting a lot, and too loud to tune out, so I listened to some free background music I'd downloaded for the backing track of a video demo I'd produced. The music was very innocuous and repetitive and I played it on a loop. That worked pretty well. I also sometimes use headphones with no sound just as a visual "don't talk to me" sign. That's pretty effective if you need to get on with work and don't have time for chatting.

The "meh" effect

It's Monday morning and the weekend just wasn't long enough, or you had a bad night's sleep, or you had an awful commute to work. You need to find something to raise your spirits, shake off those negative feelings and get yourself into a frame of mind where you want to do some good work. How you do this is going to depend on your own psychological traits and what works best for you. So if rewards work for you, you could promise yourself a reward of some sort if you get a realistically achievable amount of work done - just to get you going. For example: if I write 2 decent-sized help topics by lunchtime I'll buy myself a slice of chocolate cake to have with my coffee at lunch.

Meetings

Avoid attending meetings that you don't really need to attend. Can someone else who's going to the meeting report back to you with a highlights version of what was discussed? If you need to go along to the meeting can you be called into it just the bits that directly concern you and then duck out when the discussion moves on? If not, and it's a long meeting, can you take in a laptop and do some work (even just catching up on email) while other attendees are discussing issues that don't concern you? For all meetings, make sure they're time boxed. If the meeting is scheduled from 2 till 3, make sure everyone knows that you've got something you need to do at 3. If you can, time-box contributions within meetings. We use a little application called Dinner Timer [LINK AND PIC] that gives the person raising an issue a set time to discuss that issue. It counts down on the screen and sounds an alarm at the end of the allotted time, at which point the meeting moves on to the next issue.

When you're in the zone, stick with it

Working late when things aren't going and you're having an unproductive day isn't particularly smart - better just to go home and tell yourself you'll get in early the next day. Go home, relax, have a nice meal, have a long soak in the bath, get a good night's sleep. But when you *are* in the writing zone, hang on in there and make the most of it.

Give yourself realistic deadlines

Nobody works efficiently if they're working under stress. If you make your own schedules, try to make sure the dates are achievable. If someone else gives you a schedule, don't agree to dates unless they're achievable. It's going to be less stress overall if you have a bit of aggravation up front renegotiating a schedule that has a better chance of success.

Don't expect to always be able to get in the zone

When you're working on a larger project (e.g. an iteration of development on a new product) you have more chance of getting in the writing zone and having really productive days. But for some types of documentation work that's just not going to happen.

Recommended applications

Adobe Lightroom: http://www.adobe.com/products/photoshoplightroom/
 
Microsoft PhotoSynth: http://photosynth.net

Foldersizes: http://www.foldersizes.com

Recommended podcasts

Steven Fry's Podgrams

Right now the RSS feed for this podcast is broken, but here's a link to Steven Fry's Web site:
http://www.stephenfry.com/media/

A Way With Words

KPBS Radio in San Diego
http://www.waywordradio.org
http://feeds.waywordradio.org/awwwpodcast

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

In this, the second in a series of three podcasts, I talk to my 17-year-old daughter, Martha Christie about how she uses computers at school and at home.

Of online help Martha says:

"Those things drive me crazy. I don't think I've ever actually used any of those help systems for anything on the computer. I just don't find them useful at all.
...
There's so much writing to read and I hate that kind of thing. It's like ... if you get like a help manual with something you just throw it away before you start
...
I just can't read through it all. I'd rather just try it and then if it goes wrong I just scrap it and start again."

On the most effective way of learning, she says:

"If you want to learn something, asking a person is the best way to do it."

"I don't think I just want to be told the answer ... Getting something explained to you and getting it shown to you is different from just getting told an answer. Like if I asked a teacher for help and they just told me the answer, I wouldn't be like: 'Oh that's great, thanks' ... The best teachers don't tell you an answer - they tell you how to find the answer yourself."

She makes an interesting point about how when she wants to do something on the computer she'd naturally try and use one of the applications that are already on the computer - even if it wasn't purpose built for the thing she wanted to do - rather than search for, download and install a new application from the Internet.

I also found it revealing that she wasn't aware that most help systems for applications have an index and a search facility.

She didn't like the idea of help videos, because she wouldn't want to sit through a whole video to find out how to do something.

Finally, she's also the only person I know who's ever had anything good to say about the Microsoft Office Assistant dog. 

One of the software applications mentioned in the interview is:

Painter Classic
Metacreations Painter Classic came bundled with a Wacom tablet I bought years ago. Used with a drawing tablet it was a very impressive bit of software. Corel bought Metacreations and the latest incarnation of that software is Painter X (i.e. version 10).

http://www.corel.com/servlet/Satellite/gb/en/Product/1166553885783

This is one of the paintings Martha created using Painter Classic, in 2003, when she was twelve:

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:


comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:


http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

This extremely ad hoc podcast (we didn't plan to do one, but Graham suggest it and offered to buy me lunch, so it seemed like a good idea), was recorded in the food court at East Kilbride shopping centre. The photo shows Graham in the queue at the salad bar, trying to avoid being in the picture.

We talk about what we've been doing since our last podcast. Topics include:

• ISTC Conference 2008
• UA Europe Conference 2008
• Is is worth going to tech writer conferences? What do you get out of it?
• Why are people still talking so much about DITA?
• Geoffrey Pullum and Grammar Nazism
• "supercede" or "supersede"?
• Roadmap announced for a DITA version of Flare
• Benefits to customers and technical writers of hosted Web help

Recommended Web site: Language Log

Recommended podcast: Napoleon 101 Podcast

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

In this, the first of a series of three podcasts, I talk to my mum, Margo Christie about why she decided - quite recently - to buy herself a laptop. She describes how she learned to use a computer and what she uses it for now.

The books mentioned in the recording are:

• Easy PC: How to Use Your First Computer by Kenneth Mole
• The Internet for the Older Generation by Jim Gatenby

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

First, Graham talks to Mike Hamilton from MadCap Software about recent and future software releases and some of the new features and improvements in Flare 4.

Andrew Jackson of Pacific Blue Solutions gave a presentation on information mapping. He gives an overview of what information mapping is all about, why it’s relevant for technical writers and how you go about learning how to use information mapping.

In the final segment of the podcast, Graham gets “an assorted bunch of tech authors” (John, Chris, Katja and Paul) to share their thoughts about the conference and to discuss technical authoring in general.

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

I talk to Mike Hamilton from Madcap Software about the newly released version 4 of Flare. He describes a lot of the new features and explains the relationship between Flare and Blaze. Mike also mentions the work currently underway at Madcap to produce a DITA version of Flare.

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

Writing tips

1. Copying and pasting formatting in Microsoft Word.

   Select some text that has the formatting you want to copy.

   Press Ctrl + Shift + c.

   Select the text you want to apply the formatting to.

   Press Ctrl + Shift + v.

2. Keyboard shortcut to choose a style in Flare 4.

   Press Ctrl + h to bring up a style popup while you are editing text.

Application recommendations

Windows Live Writer

Podcast recommendations

The Definitive Word
Includes liberal use of the f word. Is that the definitive word?

Get in touch!

I’d love to know who’s listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com

Or just let me know you’ve listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast: http://feeds.feedburner.com/itauthor

Simplification * Keep documentation just simple enough, but not too simple * Write the fewest documents with least overlap Determining What to Document * Focus on the needs of the actual customers(s) of the document * The customer determines sufficiency Determining When to Document * Iterate, iterate, iterate: * Update only when it hurts General * Treat documentation like a requirement * Require people to justify documentation requests We also also discuss our writing tips, software recommendations and podcasts we've been listening to. Software we mentioned:

fileinfo.net

writerriver.com

Keepass

Podcast recommendations

The Penny Arcade Podcast:

  RSS feed: http://www.penny-arcade.com/padlc.xml Dan Carlin's Hardcore History: RSS feed: http://www.dancarlin.com/dchh.xml

Other links

Testing documentation: http://www.onemanwrites.co.uk/2008/08/07/testingdocumentation/ The Almighty Thud by Martin Fowler: http://martinfowler.com/distributedComputing/thud.html

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Subscribe to the podcast:   http://feeds.feedburner.com/itauthor

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.



Subscribe to the podcast 

• What kind of skills do you need to be a technical writer?
• What's the difference between an information designer, a technical communicator and a technical writer?
• Which is the worst of the "six biggest mistakes project managers make with documentation"?
• Is there still a demand for printed manuals, and if so, why?
• What does Cherryleaf offer as a recruitment company that other, bigger recruitment companies can't?
• What does the future hold for technical writers?

I encourage you to have a look at the Cherryleaf website. The monthly newsletter is well worth signing up for. There are a number of interesting articles and there's also a blog (for example, you might want to check out the post Ellis referred to on the secrets of effective technical authors). By the way, I claimed during the conversation that there's no degree course in technical writing. What I think I meant was that in all the many, many CVs I've read while trying to recruit a technical author, I've never come across a candidate who has been formally trained in technical writing. However, as Ellis mentions, Coventry University run several courses in Media and Communication. Also, Sheffield Hallam University offers a postgraduate distance learning course for a diploma in Technical Communication.

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.



Subscribe to the podcast



Why not get emailed next time I publish a podcast?

Enter your email address:

Preview

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.



Subscribe to the podcast



Why not get emailed next time I publish a podcast?

Enter your email address:

  Preview

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.



Subscribe to the podcast



Why not get emailed next time I publish a podcast?

Enter your email address:

Preview

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.



Subscribe to the podcast



Why not get emailed next time I publish a podcast?

Enter your email address:

Preview

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.



Subscribe to the podcast



Why not get emailed next time I publish a podcast?

Enter your email address:

Preview

My thanks go out to Tom for agreeing to be my first interviewee on the ITauthor podcast, and also for some useful comments he gave me outside of the interview about the level of some of the content on some of my previous podcasts.

Get in touch!



I'd love to know who's listening, where you are and what you think of the podcast, so contact me at:

comments==AT==itauthor==DOT==com



Or just let me know you've listened in by putting a pin in the ITauthor map at:

http://www.frappr.com/itauthor



The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music by going to the Podsafe Music Network.



Subscribe to the podcast



Why not get emailed next time I publish a podcast?

Enter your email address:

Preview



Not sure why you’d want to, but you can see my online Web page bookmarks at:

http://del.icio.us/itauthor

I start off with a short recap of what’s been happening in tech authoring while I’ve been away.

Most of this show is about DocBook and the DocBook XSL Stylesheets. More about DocBook at:
http://en.wikipedia.org/wiki/Docbook

There’s also a really nice tutorial at:
http://www.codeproject.com/winhelp/docbook_howto.asp
which includes some very handy tips about using sed and make to automate processes at the end of the article. For an example of Web pages created from DocBook source, using the DocBook XSL stylesheets, see:
http://www.sagehill.net/docbookxsl/

This is pretty much what you get, out of the box, when you do a chunked transformation of a whole book’s worth of DocBook. Not pretty, but functional.

eDE (e-novative DocBook Environment) is a wrap-up of various tools that provides a simple command-line interface to processing DocBook files and outputting HTML, PDF or HTML Help. You might find it easier to install and use than explicitly installing xsltproc and the DocBook stylesheets and running using them directly. However, I think you get more control by doing it yourself. It depends whether the out-of-the-box results are good enough for you, or whether you need to adjust the results (in which case eDE is probably not for you):
http://www.e-novative.info/software/ede.php

Flare version 2.0 is now out. I’ll talk about this next time round. Meanwhile, Madcap’s Marketing department have produced a flier describing what version 2.0 will offer:
www.madcapsoftware.com/support/files/downloads/mc_flare_v2.pdf
and, more importantly, you can download a free trial from the Madcap Web site.

Get in contact!

I’d love to know who’s listening and where you are, so contact me at: comments==AT==itauthor==DOT==com

Or put yourself on the ITauthor map: http://www.frappr.com/itauthor

The music I play is by Amplifico, and you can hear more of their music by going to the Podsafe Music Network (http://music.podshow.com/), clicking on Search Music and searching for Amplifico.

Not sure why you’d want to, but you can see my online Web page bookmarks at: http://del.icio.us/itauthor

Lots of background noise on this episode. Apologies for that. I will endeavour to improve the production quality of the next podcast. I’ll also try to sort out the levels in CastBlaster a bit better by next time.

Sorry no commenting on this blog any more. I got hit by a deluge of comment spam! But please send your comments to the email address in the podcast or, if possible, mail me an audio comment that I can put on the show.

Links

DocBook How To

A good nice tutorial on using DocBook.

DocBook Wiki

More information about DocBook.

MadCap Software

Go find out about what those crazy MadCap guys are up to now!

Tech Writer Voices

An interview-based podcast. Check out the interview with Mike Hamilton of MadCap Software.

ITauthor Notes - Sept 17, 2006

An entry in my ITauthor Notes blog describing how to use the XSL stylesheets.

Sound quality
I don’t know what happened with the sound quality, but it’s particularly poor. I recorded it on CastBlaster, in 10-minute chunks, moved these over to Cubase and put them together and added the music. This added some noise but the recording sounded not bad, but after exporting to MP3 the background hiss went way up and, although I tried various output options, I couldn’t improve things. So I tried running it through Clean to cut the noise, but this took forever and at the end I had something that had much less hiss, but apart from that sounded awful, so I decided to stick with the hissy version.

Next time round I might just try sticking with CastBlaster - but I’m not sure I’m up to recording one of these things live, without any editing. We’ll see. But for now you’ll just have to endure the hiss.

Have I put you off yet?

Contents
In this podcast I talk about:

1) Madcap Flare 1.0
Overall, my first impressions of Flare were very positive. I suspect future releases will do more interesting stuff. I couldn’t see many reasons to buy Flare if you already have the current version of RoboHelp, but if you’re new to help authoring and you need to buy an application, or you need to upgrade from an old version of RoboHelp, then Flare’s the way to go.

I mention an error message I got when switching from tag view. See: www.itauthor.com/notes/archives/2006/04/flare_error_mes.html

Some other first impressions of Flare:
www.techwr-l.com/techwhirl/archives/0602/techwhirl-0602-00050.html
www.chmtools.com/forum/techwr-robohelp-or-webworks-epublisher-for-word-2000-and-4664.html

2) FrameMaker Day
I talk about attending a FrameMaker Day organised by Mekon, including a Q&A session with Karl Matthews, Adobe product manager for FrameMaker and RoboHelp.
Mekon: http://mekon.com/
Pectora: http://www.pectora.com/
Idiom: http://www.idiominc.com/

3) CVS and Subversion
Subversion book: http://svnbook.red-bean.com/
SVK: I mention a Perlcast interview with the creator of SVK: http://perlcast.com/2006/03/07/interview-with-chia-liang-kao/

4) Alfresco and Joomla
Article on Alfresco: www.infoworld.com/article/05/10/31/HNalfrescoopensource_1.html Alfresco demo: www.alfresco.com/products/ecm/demonstrations/ Joomla: www.joomla.org/

5) TIBCO GI ”“ Javascript/Ajax development tool
Audible Ajax podcast - interview with Kevin Hakman of TIBCO: http://ajaxian.com/archives/audible-ajax-episode-15-kevin-hakman-of-tibco
A screencast of Tibco GI by Jon Udell: http://weblog.infoworld.com/udell/2005/05/25.html

6) ITauthor Frappr map (please add a pin)
www.frappr.com/itauthor

7) Amplifico
On the Podsafe Music Network: http://music.podshow.com/index.php
Website: http://www.amplifico.net/

Well, actually the reason for the long gap between podcast 3 and this one is partly because of Christmas and partly because I just haven t got round to it. But here it is, started on January 31st, so technically January's podcast, in this episode I talk about Madcap Flare and why I think it might be the replacement for RoboHelp, but probably won't be the technical authoring application we've all been waiting for.

Once again thanks to everyone who has pinned themselves on my Frappr map (www.frappr.com/itauthor).

Tech authoring products mentioned in this podcast:

• Help Manual Help Studio
• Document! X
• Doc-To-Help
• WebWorks
• ePublisher Pro for FrameMaker
• AuthorIT
• FrameMaker
• RoboHelp
• Arbortext Editor
• XMetaL Author

For details of what I did (step by step) see:

www.itauthor.com/authtools/plonezope/upgrading-to-2.1.1

By the way, in yesterday's posting I said I was using Lemon, which "used to be called iPodder". Scratch that. It's now called Juice, but it used to be called iPodder Lemon. Apparently, Apple issued a cease and desist notice to iPodder telling them to change the name to avoid any inference of a connection between them and Apple (see http://www.theinquirer.net/?article=27684).

After reading around the subject of publishing podcasts I decided to give dircaster a try. My reason for choosing dircaster was its simplicity. It's a PHP script and basically all you do is put it in a podcasts directory on your web server and then upload your MP3 podcast files into the same directory and the PHP does all the RSS stuff for you. If anyone out there has subscribed to the RSS feed for your podcast channel they get to see the new editions when they update (which is usually a scheduled operation). In other words, by simply uploading the MP3 files, your listeners get access to your new podcast via their podcast client or aggregator. The version I installed was dircaster 0.4e. See www.shadydentist.com/wordpress/archives/2004/12/23/dircaster-v04-podcasting-php-script I made the recording for my first podcast using my PDA, I then cleaned up the recording on my Windows laptop using Cubase, saved it as an MP3 then used WinSCP to move the MP3 file to the podcasts directory on my Linux Web server. If you want to listen to my first podcast (or any subsequent ones I might have done since writing this), go to http://feeds.feedburner.com/itauthor and click on the "Listen" button. Alternatively, if you want to subscribe to the podcast feed using your podcast application, just do the following:

In Juice:
1. Click the Subscriptions tab.
2. Click the Add New Feed button (+).
3. Paste the following into the URL field: http://feeds.feedburner.com/itauthor
4. Select the "ITauthor" subscription.
5. Select the Episode to download.
6. Click the Check/Download Selected Feed button (V).
7. If you've set up the Preference to play the download right after it's download you'll hear the podcast. If not, double-click the podcast edition in the Downloads tab.

In Apple iTunes:
1. Select Advanced > Subscribe to Podcast.
2. Paste the following into the URL field: http://feeds.feedburner.com/itauthor
3. Double-click ITauthor in the Podcast list. It works!

If you want to try creating your own podcast feed there's an excellent article called Where to Submit Your Podcasts: Best Podcast Search Engines and Directories on masternewmedia.org that contains a long list of podcast directories you can submit your feed URL to. Another useful thing to do is to ping audio.weblogs.com each time you publish a new podcast. You can do this using the form at: http://audio.weblogs.com/pingSiteForm