The context menu for a span in Flare 6.0

Madcap Flare 6.1 has been out for a while now and, if you haven't already, you really should upgrade to it if you're a Flare user – and if you're a tech writer and you're not using Flare to produce online help then do yourself a favour and go and take a look at it.

Release 6.1 is confirmation that Flare is the best documentation creation tool out there. In particular, for me, this release is important because it allows you to use Subversion (SVN) from within Flare, which was broken in 6.0.

However ...

Isn't it annoying when a new release of a software application removes something that you'd got used to using in previous releases? In Flare 6.1 – for no discernable reason – you can no longer change the attributes of a span by clicking on the "span" marker. We use the Name attribute of a span with a certain class to create a link to our own home-grown glossary popups. This worked great in previous releases, as follows:

• Select a word or phrase
• Choose span.glossPop from the Styles list
• Click "span" > Name
• Add the appropriate glossary reference

In 6.1 you can't do this any more. Now, just to increase your click count, you have to get to the Manage Named Elements dialog box from the Format menu.

Okay, so there's a workaround. But why remove something that was useful and we'd got used to using? Is it a bug or is there some sort of rationale to this change? I'll raise a Support call and report back.

But in my view more clicks to achieve the same result is never a good thing.

I have some PHP script that grabs some data out of a MySQL table. However, rather than display it in the normal way:

I want to swap round the rows and columns so that I display it like this:

The thing to be aware of is that when you use mysql_fetch_assoc to get stuff out of a database, for example:

what you get back is an associative array (that's a hash for folks like me who learnt this stuff in Perl before arriving at PHP). So in the above example $resultArray is an associative array - that is, a set of key/value pairs where the key is the field name and the value is the value in that field for that record. Each iteration through the while loop you get a different record.

So, in effect, it's like an array of associative arrays.

However, what you want in order to be able to swap round fields and columns is an associative array of arrays - that is, a set of key/value pairs where each key is a field name and each value is an array of the values for that field in each record in the data set. So what you need to do is:

• Iterate through each record in the data set (i.e. each row in your results) .
• For each field in the record, assign the field value to an array, a reference to which is the value of the key/value pair in the outer associative array.

If it sounds complicated, then I'm glad I'm not the only one. Actually, it's probably easier to understand by looking at the code:

assocArrayOfArrays-example-PrettyPrinting.html - This is a syntax-highlighted representation of the PHP.
assocArrayOfArrays-example.php.txt - This is the actual PHP saved as a .txt file so that you can see and download it.

And here's the PHP in action:
assocArrayOfArrays-example.php

And, lo and behold, version control is now working again in release 6.1.

Thanks Madcap - much appreciated!

In discussing what a manager can do, faced with this situation, he quotes President Harry Truman:

It is amazing what you can accomplish if you do not care who gets the credit.

As I write my download connection is 0.06 Mb/s. Yes, that's right, a measly 60 kilobits per second. That means a long, long wait between clicking a link on a Web page and eventually having the result page in a readable state in front of you.

At this speed iTunes and Tweetdeck simply don't work.

This, I'm assuming, is due to Sky's wonderful Traffic Management policy: the more useful you find the internet, the more we're going to try and discourage you from using it.

So I logged into my Sky account and went to try and raise a Support call. Here's the form they present you with, saying: "tell us about your query":

What?!!! In that space? Now they're really just rubbing salt in my wounds.

OK, so, after writing out my complaint elsewhere and then copying it into this field and submitting it, lo and behold, as I suspected (but didn't want to assume, in case I had to get all the way back there again if I was wrong) there's a follow-up screen where you can pick from options and then you can send Sky Support an email. But honestly! Usability: ever heard of it Sky? Did you ever roadtest this on anyone? Did you ever think how it feels to spend 10 minutes on a grindingly slow connection waiting for pages to slowly load, just to get to this page.

So I'm off to have a cold beer now, watch some football and cool down a bit.

And maybe by tomorrow this page will have uploaded to Web host. And maybe Sky will get back to me. But at the moment I'm not optimistic.

But spelling's different. Isn't it?

Surely we can never afford to lower our defences against misspelling? Spelling comes in two flavours: right and wrong. Right? And if you let spelling errors slip through then no one will be able to understand what you're on about. One spelling slip and your credibility crumbles ...  You get the picture.

Well, that's what I've always thought. So I was surprisingly interested in an email Patricia forwarded on to me today. "Surprisingly" because it was one of those pass-it-on emails that used to do the rounds but which, thankfully, you don't get so much any more. Usually they have a list of lame jokes or pictures and at the end they tell you to email it to your friends. Usually I save them straight to my Trash folder. But this one contained some simple editing-type tests (for example, spotting a single N in a block of Ms) and then ended with this:

I cdnuolt blveiee that I cluod aulaclty uesdnatnrd what I was rdanieg. The phaonmneal pweor of the hmuan mnid, aoccdrnig to a rscheearch at Cmabrigde Uinervtisy, it dseno't mtaetr in what oerdr the ltteres in a word are, the olny iproamtnt tihng is that the frsit and last ltteer be in the rghit pclae. The rset can be a taotl mses and you can still raed it whotuit a pboerlm. This is bcuseae the huamn mnid deos not raed ervey lteter by istlef, but the word as a wlohe. Azanmig huh? Yaeh and I awlyas tghuhot slpeling was ipmorantt! If you can raed this forwrad it 

It is amazing how easy it is to read this. And it did make me stop and ask myself: maybe I should lay off the obsessive marking up of every piddling little spelling mistake when I'm sent documents to review. As long as the first and last letter are correct, why worry?

Yeh, right!

I take a liberal, progressive approach to grammar. But I think I'll stick to my hard-line approach to spelling.

A loved child has many names.

I'd like to think that maybe the multiplicity of titles given to people who do the same or similar role as me suggests that we are a well beloved function within our organisations. However, experience tends to suggest otherwise. More likely is that the many names signify an identity crisis in the profession, or an attempt at aggrandisement or a search for job security - or a mixture of these and other factors.

Whatever the reason, I thought I'd list some of the names I've come across for jobs that, behind the title, can sometimes be very similar:

• communications officer
• content curator
• documentation developer
• e-learning author
• information architect
• information designer
• information engineer
• knowledge engineer
• technical author (inf. tech author or TA)
• technical communicator
• technical writer (inf: tech writer)
• user assistance developer

Have you come across any others?

This got a little bit nearer with HTML5, but Firefox 3.6 doesn't support MP3 files (which most people still use for audio files on the Web), just Ogg Vorbis. IE9, on the other hand, supports MP3 but not Ogg.

There is a jQuery plugin called jPlayer which goes part of the way to providing a cross-browser solution, but it's a very techie solution and not easy to configure.

So, until all of this gets sorted out finally, most of us just follow the path of least resistance and use a Flash-based audio player and accept that, because Steve Jobs is on a crusade to kill off Flash, no one browsing your pages on an iPhone or an iPad is going to see the player.

As I write this, in June 2010, the podcast pages I produce to accompany my podcasts use a Flash player that comes as part of the Blubrry PowerPress plugin for WordPress. And at the top of the sidebar on each page I use the Easylistener player. Here's a screenshot, just to remember it by, as it's only a matter of time before I have to remove it:

I periodically scour the internet for small, nice-looking audio players that can be pointed at an RSS feed, and Easylistener is the only one I've found that I really like.

William White describes the origins of Easylistener:

Easylistener was developed in the Yahoo! Media Innovation Group by William White and Joseph Magnani. It was inspired by the work of Fabricio Zuardi, Lucas Gonze and many other amazing and talented engineers working for Yahoo! Music in San Diego and Santa Monica, who were developing the Yahoo! Media Player.

Easylistener feeds off XSPF, a venerable XML format for playlists. The little chunk of code that places the player on your Web page includes a reference to a Web site that will take the URL of a Web page and will go and read that page, extract details of any audio files it finds and build them into XSPF that it then feeds back to the Easylistener Flash application.

The trouble is all of this was developed by Yahoo! and they provided the "playthispage" service that produced the XSPF for the player. But Yahoo! lost interest in (or never really noticed) Easylistener, so it was left to rot. Back in July of last year I blogged that the URL for the "playthispage" service no longer worked, which resulted in no content appearing in the player. After a while they seemed to have moved it to another server and I got the player working again. However, it recently stopped again, and this time I was sure it was dead for good.

I emailed William White, who had commented on my original blog post, and I asked if he could help. He got back to me to say he'd set up a PHP script that provided the same XSPF generation service. As a result, for the time being, the player is working again.

To get it working again I added:

playthispage_url =http://musiclibre.org/playthispage/?url=

So my embed element now looks like this (note: the flashVars value should be one long string, I've broken it into lines here just for good looks):

<p style="margin-left:-10px; margin-top:0">     
    <embed src='http://l.yimg.com/us.yimg.com/i/mig/playlistbadge/25.swf?referer='   
       width='170'     
       height='200'     
       wmode='transparent'     
       flashVars='playlist_url=http://www.itauthor.com/category/podcasts/feed&   
          playthispage_url=http://musiclibre.org/playthispage/?url=&   
          rounded_corner=1&skin_color_1=0,-100,-29,18&skin_color_2=0,-100,-27,20'   
       type='application/x-shockwave-flash'     
       pluginspage='http://www.adobe.com/go/getflashplayer'     
   />                                                                              
</p>  

However, if you  want to use Easylistener to your own Web pages, the easy way to get it is to go to:
http://www.musiclibre.org/easylistener/

There's a nice little Web application there for setting the page that gets scraped for content and choosing the way you want the player to look. You then just copy the embed code and change "http://webjay.org/flash/xspf_player" to either "http://musiclibre.org/xspf_player" or "http://musiclibre.org/dark_player".

For example, here's one I just went and grabbed.

And if you don't see anything (or the player is empty), it means it's broken again.

Such a shame Yahoo! didn't continue supporting this because it's still way better than anything else out there that tries to do the same thing.

Then this evening I read this blog post by Mark Metcalfe: Tech Writers Need to Learn to Say Yes

Maybe if I'd read this I would have set out the options, rather than saying no. However, I worry that it's not quite as easy as Mark suggests. Very often requests for time come out of the blue and the start date is today. If you give a qualified yes, the person may hear what they want to hear - the yes - and conveniently forget the discussion of workload, cost and priorities. Often you are responsible to deliver work for several people at a similar managerial level and each of them thinks their work is the priority. Escalating to a more senior managerial level can be problematic because escalation generally has to happen through one of the managers concerned, who have little incentive to trouble their boss for arbitration.

So maybe, as well as learning to say yes more often, the tech writer needs to learn diplomacy and negotiation skills. Give a tentative yes to everybody and then get them to sort it out between them. Get everybody in a room if possible. Who's going to give way, because there's only so much you can do? So doing C means rescheduling A and B.

But if doing C is the best thing for the company then it would be crazy not to do it just because you'd already planned to work full-time on A and B.

I'm not sure I agree with the order Ellis places these in, so this is my reordering (and rewording) of the four levels:

• Ask a friend - usually by instant messaging, maybe by text or email, increasingly via twitter
• Ask the local expert - Ellis calls this the 50-foot guru: "the person within 50 foot of your desk who is more knowledgeable than you"
• Search for help yourself - most of the time this means Googling for it. You might use another search engine, but Google remains the default means of finding information for most computer users
• Call support - this might mean phoning your internal IT helpdesk at work, or it might mean emailing the company that produces the software with a support question and then waiting for a reply

I haven't numbered this list because the order is debatable. Some people don't like admitting they don't know stuff, so they'll always search for themselves before asking someone else. Other people have the attitude: I've got a helpdesk and I'm gonna use it - and they'll pick up the phone to support whenever they get stuck. On the other hand, I suspect people increasingly aren't prepared to wait for a reply to a support call - they've got to have the answer right now, which is usually when a local expert is required. And then for some any excuse is a good excuse to text, tweet or instant message their friends.

These four levels relate particularly to younger users - Ellis says "primarily those under 27", I'm not sure why 27 specifically, but I know what he means. Google first emerged into the public consciousness in 1998, when today's 27 year olds were 15. By that time ICQ and AIM were well established instant messaging platforms. So people around that age and younger have lived their entire adult lives in the Google world, and often they've been using instant messaging as an everyday way of chatting to friends since they were in school. I definitely think people in their late twenties and below are less prepared to invest time digging around researching a subject to find answers than people over 40 (like me).

But even I sometimes don't bother looking up the documentation provided by the software company. In particular, these days I never bother looking up the help systems in Microsoft Office products. Experience has time and time again proved to me that it's simply a waste of time. There's obviously lots of information available from Microsoft - usually when you search the Word or Excel help you get lots of results - but you just spend far too long doing all the leg work, looking through page after page, and often don't find what you're looking for. Go to Google and search from there and you'll usually find the information you need among the hits on the first page of results.

But going back to the four levels of support identified by Ellis Pratt. What about the manual, he asks, where does that fit in? Well, in many cases, that's now one of those things users find by Googling:

many may not recognise it as a manual. It might not have an index, page numbers or a table of contents, but it serves the same function.

The traditional manual is, in most cases, an anachronism now. And traditional ways of creating documentation, based on the way we used to produce printed manuals, are equally anachronistic, even if they're now applied to creating online help. And hey, if most people get their answers about using an application by asking their friends or the local expert, do we even need documentation at all?

Well the answer is yes. Information still needs to be packaged and presented. It's just that this can be done in a different way now, and the information very often gets to the end consumer second or third hand. For a variety of psychological and sociological reasons there are still people who are prepared to invest time learning all about an application. This person becomes the guru. The guru gains some sort of reward from this role and he/she passes on the information to others, who can then share the information with their friends. These second-hand recipients of knowledge are not gurus but they can still, from time to time, supply answers to IMs or tweets asking for help.

Apart from the gurus, the other group that still regularly finds documentation useful is support staff. They'll search a help system on behalf of users who can't be bothered to do so for themselves. And the support staff may even be involved in writing the documentation (this is the ScreenSteps philosophy). Either way, the documentation is the knowledgebase or knowledge repository in which answers to users' questions are to be found, and the support staff can answer a support call with a link to a page in the documentation - typically a specific help topic.

As technical writers we should have no fear that there will be no work for us to do in a few years. Software is going to be around for some time to come and all but the simplest software applications need some sort of user assistance. But it might be that we're not working in a role called "technical writer" - and we almost certainly won't be writing traditional manuals with a title page, table of contents, chapters, appendixes and an index.

But then - despite what many people imagine - I believe most user assistance professionals aren't spending much of their time writing that sort of traditional manual right now anyway.

Next, after you've got a decent understanding of the subject matter, you then start looking at the application (what there is of it so far, plus any plans/designs/user stories you can find for what will be appearing in future iterations of work) and you talk to the project managers, developers and testers, and hopefully you also get to talk to some beta users or user advocates.

Then you can begin to plan your help system. What's the top-level structure going to look like? How are you going to break it down into sections and subsections. Several years ago I worked on a help system where we spent weeks drawing up a complete TOC for the help, and getting it reviewed and signed off, before we started writing a single topic. Needless to say, that was long before I'd heard of the Agile development approach.

But my previous couple of posts have got me thinking. If we could do away with the TOC maybe we could do away with any structure outside of individual topics. And if we could do that then we could cut out a lot of the preliminary process outlined above. It might mean we could get to the point of creating useful content much more quickly.

The ScreenSteps approach is worth considering here. It goes something like this:

• At initial release, the help system just contains 10-20 questions that you know users are likely to have
• After release of the software, the help system grows over time as users ask questions and you add the answers to those questions to the help. But note: you only add new content in response to real questions
• New help topics get dropped into the help as you write them. Users can find them in a search and you can send them a link that'll get them straight to that topic. Consumers of the help don't need a TOC.

The ScreenSteps Documentation home page is a great example of a simple documentation interface:

Notice how predominant the search box is. You could claim this page has a table of contents - it kind of does - but it's not like the traditional, elaborate expanding-tree TOCs you find in many online help systems. It's just a simple series of links. If you click one of these links you get to a similar page with more links, from which you go to an actual topic. So there's never more than one hierarchical level of links on screen at once, and you're never more than two clicks from a help topic.

And what I really like is that this allows you to keep adding topics without always having to decide where to place a link in a tree TOC. Just write the topic and get it in there for users to see. If it merits a link in one of the secondary links pages you can go and add one, but I'm pretty sure most people using this system will get to content via a search.

I'm convinced these days the majority of us are searchers rather than looker-uppers. So the search box serves the majority searcher community, and the links are there:

1. For the minority looker-uppers
2. To direct people quickly to popular topics. Hopefully you're able to use the logs from your web server to spot the topics that most people go to and you can design appropriate first and second-level links to get people there fast.

Maybe it's time to retire the old tri-pane online help:

Apologies to ESRI. I'm really not slagging their online help (acually I think it's very good). It's just the first internet-visible tri-pane WebHelp I could think of.

Tech Pubs have almost no interaction with actual users ... they rarely ask users what they need.

This lack of direct connection with end users means that tech pubs has no idea what information is actually important to their users. They don’t know what questions the users have. They don’t know how best to answer those questions. The end result is software documentation that meets the requirements of “stakeholders” but not users.

Guess what? The stakeholders aren’t going to use the documentation.

It's thought-provoking stuff. I also love an article on the bluemango website entitled "5 Steps to Improving Your Software Documentation". I think I love it because I feel like I wrote it myself. It sums up some of the things I believe in about documenting software - for example: make good use of screenshots and videos and, whatever you do, don't just go through the application screen by screen writing up a description of what's on each screen.

The guys at ScreenSteps also have an interesting take on planning documentation: don't plan.

You can't possibly anticipate every question your users will ask. So don't. Just: write down actual questions people have and then answer them.

This video, while being very much a marketing piece aimed at selling ScreenSteps, contains a lot of very sensible ideas that are worth thinking about:

The don't plan your documentation, just answer users' questions approach sounds great. But it requires a shift in how documentation gets created that will involve a whole restructuring of roles and responsibilities between departments. This might be too much of a leap for some businesses to make.

And what happens if you're working on a new system that hasn't got any users yet? This shouldn't be a problem if you have a truly Agile development process. In this case real live would-be users are getting their hands on beta versions of parts of the system at regular intervals, as it's being developed. The trick for those responsible in creating the documentation has got to be involvement in this process: tapping into the reactions of those early users, soliciting questions from them and using those questions to shape your documentation.

However, for old-style software development (long development cycles against long lists of requirements, followed by an eventual release) it's going to be difficult to use the ScreenSteps approach to come up with an initial help system.

Here's another ScreenSteps quote that echoes a personal mantra of mine:

People don't read documentation, they reference it.

Your users aren’t going to cuddle up by the fire and read your software manual. They are going to read it when they get “stuck” using your software. They are going to read it when they have a question. Make sure that your documentation makes it easy for them to find the answers to their questions.

This is something I repeatedly tell in-house staff (generally, but not exclusively, staff who've worked in the software development business for years) who still equate documentation with printed manuals and who expect technical writers to spend most of their time creating printed books. No! That's not what we're about. We're about helping users to get the most out of the software and we do that in whatever way is most effective - and that's usually not in the form of a printed book.

The bluemango website and their blog (Talking in Pictures) are worth having a browse around. Lots of really sound advice in there. Note: I'm not recommending ScreenSteps as a documentation platform - I've never used it, I just discovered it today - but it definitely looks like a great solution for documenting certain types of software applications.

http://www.bluemangolearning.com/blog/2010/05/who-should-write-your-software-documentation-not-tech-pubs/

I feel like I could have written this myself!

Tom describes helping out with user support for an application. He also works on the online help for this application. He describes how useful this contact with users can be. He writes:

I know that this support role, while annoying at times, is also advantageous because it gives me an insight into the real problems users are having. Through this close connection and user-informed perspective, my help can provide real answers that users want.

Talking to users. Wow! That's how it should work. My own experience, documenting enterprise-level software, is that the tech writers and the end users often never come into contact. Our end users (yes, I know, horrible expression, but what I mean is not the administrative users, or the managers, or the customer’s support staff, and not the decision makers who you sold the system to originally but who will never actually use it, but the people who have to use the software day-in, day-out as part of their jobs) … hang on, let me start that sentence again. Our end users contact their internal support staff and, if they can't help, those support people log a support call with our third-party call centre and it then gets picked up by our support people who generally manage to solve the issue very quickly and without reference to anyone else. The tech writers usually never find out about these support calls unless they take the time to check the support system regularly, or they hang out with the support guys (which tends not to happen just because we're in a different part of the building). So it's not unusual for tech writers to work on a product for months, or years, and never talk to an end user. Their knowledge of the end user tends to come second hand, through the product manager or some other SME. And it just stands to reason that if you had a direct line to your end users your documentation would inevitably be much more fit for purpose, and would get better over time.

So Tom’s post got me thinking: maybe working periodically in support is something all tech writers should do.

Tom’s post also referred to an old ITauthor podcast where Graham and I discussed how much you should document. I must admit I’d completely forgotten about that one. I should probably listen to it again some time.

But what I think I probably said in that podcast, and it’s what I really believe, is that tech writers have to get away from the habit of just bashing on and documenting stuff. Time and time again I've seen tech writers succumb to the temptation to just document whatever they see in the user interface. This is always going to result in pointlessly bloated documentation. It's the scatter-gun approach: "How should I know what users will want to know about? So I'm just going to document as much as possible."

I'm convinced the result is that a lot of time is wasted documenting things that, in a well designed interface, are obvious to the user. Those things tend to be the things users do most of the time: the basic, nuts and bolts operations that were in the original design of the application. The interface makes it easy to figure out how to do those things, so users don't need help with that. It tends to be the secondary things - the stuff that got added to the application in later iterations, and which are accessed via a menu item rather than being immediately obvious - it's those things that users tend to need some help with. But generally, to make the initial help system at least adequate for release, the tech writer needs to do a lot of thinking up front, ask a lot of questions, and get a pretty good understanding of the workflow through the application, and what tasks different sorts of users are trying to complete, and a fairly clear picture of how the application will really be used in day-to-day practice, before he or she starts writing help topics.

Tom’s post and the comments after it talk about how, as a result of users asking questions, and perhaps contributing answers to user forums, a help system can continue to grow and improve. And it’s obviously a good idea: after the initial, good-enough-for-release version of the help, with the assistance of users the user assistance gets better and better over time. In practice I think this is still all too often an aspiration rather than a reality.

Tom, who I’m assuming works on hosted WebHelp, describes how whenever he gets a support question that is now answered in the help, he goes and writes a topic answering the question, rebuilds the help and then replies to the user with a reference to the new topic. I think this is a great idea, but it only works where you host the WebHelp. If your customers host the help on their own server, or if the online help is traditional client-side CHM files, then it can be months before users see the next version of the help system.

One of the comments I really liked was by Larry Kunz. He writes:

As community-based documentation really takes off, I envision users’ requests going into forums (or something similar), and the answers being posted to the same forums - either by you or by other users. If the user community really becomes active, your role evolves into more of a curator (editing user-generated content and tagging it for findability) and less of a content producer.

Is this yet another alternative title for our role: information curator?

After commenting on the post I continued to mull it over, in particular the issue of finding information in a help system that just keeps growing and growing. Tom writes:

in a thoroughly massive help file, it becomes more difficult to find information. If a user expands a TOC to find dozens of subfolders and sub-subfolders and scores of topics within each subfolder, the system of navigation will become intimidating and cumbersome. The user will revert to keyword searches as a primary means of finding searches. After a few fruitless keyword searches without the right results, he or she may simply give up. The easy-to-use navigation system suffocates under the load of help topics

This gave me a radical thought. Isn’t it about time to do away with the TOC and the index in online help systems? Both the table of contents and the index features of printed books that were pulled across into online help, way before Google appeared in our lives, and maybe they’re just not appropriate for online help.

Surely what we need is really good search results. How do 99.9999…% of people find information online? Through a search engine. The more I think about it the more convinced I am that, if your online help had a great search engine, you wouldn’t need to worry about the system growing and growing as questions and feedback from users helped you add the information they wanted to find. Better still would be the situation where a user community forum helped you build into the help the answers to questions people had actually asked, rather than the tech writer’s best guess of what they might ask.

So come on help tool vendors, give us really good search results. The search functionality in Madcap Flare’s WebHelp leaves a lot to be desired - try doing quoted searches. If you publish WebHelp that’s publicly visible, you can use Google as your search engine and, while far from perfect, that’s probably going to give you the best available search results right now. But what if your WebHelp is hosted on an isolated corporate network? Or what if you’re tied to delivering old-style CHM help for the foreseeable future? Back to the help tool vendors in that case. Come on: give us really good search results.

From making a habit of talking to non-technical people about how they figure out how to use software, I’m convinced the majority of people wouldn’t bat an eyelid if the TOC and index disappeared from help system and the landing page for help was just a simple, Google-like page with a box to type in your question and a big old Search button.

I'm not sure I'm sold on Agilewords. How's it better than all the countless other ways of doing shared documents? How's it better for reviewing than Acrobat Pro?

But these tips are worth a look.

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.

Naturally, I wanted a Mac. But I couldn't afford one.*  So instead I settled for an Amstrad PCW 9512, which couldn't do page layout but, as an alternative to a typewriter, saved me a lot of Tippex by allowing me to edit my essays on screen before printing them out to the daisy-wheel printer that came as part of the package. I had a small collection of typewriters that immediately became obsolete (although, all these years later, I still have them - but probably not for much longer).

A couple of months back I had a clear out and I took the PCW - which had been sitting, unused in a big cardboard box in a cupboard for the past twelve years since we moved house - and I added it to a pile of slightly less ancient computer equipment at our local recycling centre (otherwise known as "the dump").

This weekend I had another chucking out session and I came across the PCW keyboard, a collection of the sturdily built 3" disks that the PCW used and some books, including a well-thumbed copy of the original user manual. I'd forgotten what a good piece of documentation that was. Buy almost any hardware or software now and you'll get a flimsy little pamphlet, with health and safety warnings and some basic startup instructions, printed in 23 different languages. The PCW 9512 came with a really substantial book.

The PCW 9512 was sold as a "Personal Computer Wordprocessor". Its main market was small businesses that couldn't afford an IBM PC. It came with LocoScript, word-processing software, and a mail-merge program for producing personalised copies of standard letters.

But in the back of the user manual there were sections on using Mallard Basic and Logo. I immediately got deeply fascinated by BASIC and I started buying the PCW Plus magazine every month for the program listings they published. I ended up spending hours and hours, usually late at night, writing a Pacman-type game, instead of studying (or sleeping). Eventually this game got too big and unwieldy for BASIC - and the more functionality I added to it, the slower it became - so I started rewriting it in C. At this point it was becoming a bit of an obsession, with long, compulsive coding sessions, but the arrival of my daughter snapped me out of the habit and it was then several years before I did any more coding.

However, the starting point for my real interest in software - I mean writing it, rather than writing about it - came with this manual for the PCW.  So, I'm a little loathe to consign it to the dump, but it's just part of the general clutter I'm trying to get rid of, so it's got to go.

For more details about the Amstrad PCW, have a look at it's page on Wikipedia:
http://en.wikipedia.org/wiki/Amstrad_PCW

* I haven't been able to find the price for an Apple Mac SE in 1989 but, from memory, I think it was almost £2000, whereas the PCW9512 retailed for £499 + VAT and came with a bundled printer.

Among the things that struck a chord with me was this:

"I think it was John Ruskin said, he was talking about Capitalism and he said, 'The acquisition of each new thing just engenders a new form of weariness.' And I thought, it's the most brilliant way of describing stuff: the stuff that we accrete during our lifetimes. Greg and I certainly have got to the point where we say, 'Could we get rid of this? Yes, come on let's chuck it.' It's like you're going along in your boat and you just want to make it lighter, so you can travel faster and you can go with the wind a wee bit more."

For some unfathomable reason, the podcast I was listening to is no longer available at the BBC website, so here's a link to my own copy (until the BBC tell me to take it down):

http://www.itauthor.com/wp-content/uploads/2010/04/DID-Emma-Thompson.mp3
© BBC, 2010

And - although she knows it anyway - Patricia, it's you I really love.

Technically Speaking » Review of MadCap Flare V6

Particularly worth checking out is multi-topic in XEdit.

James Shore: The Art of Agile Development: "Done Done".

Over the years I've used various feed aggregators, latterly Google Reader, to keep me informed of what the pool of bloggers I'm interested in are blogging about. I'm not a great fan of reading the news on the Web (I get my news through the radio mainly), but I know a lot of people also used to use feed aggregators to keep them up to date with news. I think this is largely a thing of the past.

In recent years I found that I was looking at Google Reader less and less. For the blogs I was really interested in, I used FeedBlitz to mail me every time a new post appeared on those blogs.*

But these days twitter has taken over as the main way I hear about stuff. I use TweetDeck as my window on twitter, Facebook and LinkedIn, rather than ever actually visiting those websites. TweetDeck gives you a column of tweets by the people you've subscribed to, a column for FaceBook, a column for LinkedIn, a column for direct message to/by you, etc. But it also allows you to add columns for searches of hash tags. So I have a column that shows any tweets containing #techwriting or #techcomm or #techcomms (the last one may be unnecessary now I think about it). This provides a fairly constant flow of links to interesting information about technical writing. And the good thing is I didn't even have to go out and find these people and subscribe to anything - I just get everything going into twitter that's been marked in this way. Amazingly (so far at least) it seems to be free from spam. And it's really useful.

I used to find Tom Johnson's community blog Writer River good for this kind of thing, and I used to post to it, now and again. But it was cumbersome to post to using the Publish2 browser plugin (which is buggy and required me to enter multiple sets of login information every time I'd cleared my browser cache - which is often when I'm working on WebHelp) - so I got fed up - it didn't seem worth the hassle. And besides, it's so easy to tweet. Aggregators and aggregated sites like Writer River seem like a part of history already. Twitter is so immediate and so easy. It's 140-character limit can be a challenge, but it turns out to be one of the best things about twitter because it prevents verbosity.

Dave Winer's metaphor about news aggregators providing a river of news turns out to fit twitter perfectly. According to the metaphor, you don't need to be by the river every minute of the day, you just go down there whenever you feel like it, or whenever you can, and take a dip - or paddle about a little. Tweets keep on flowing, you'll never read them all - so you don't worry about it.

RSS is still great for a number of things (particularly, for me, the magic of getting podcasts onto my iPod). But as a way of keeping up with blogs you like, or finding out about the big new thing, or being alerted about important news, or telling people you've blogged about something, or telling people about something interesting you've found out there on the internet, RSS just doesn't cut it any more. Twitter beats RSS hands down for all of those things.

And yes, I tweeted about this blog post. 
    

* Want to use FeedBlitz to get emailed about an updated feed? Go to https://www.feedblitz.com and scroll down to "Subscribe to any blog" then enter the URL of the feed you want emailed about (e.g. http://www.itauthor.com/feed/), then click Subscribe.

Friday/Saturday-night pub crawls in the late '70s were, for me and my band of pals, peppered with games of Defender, Galaxian (my personal favourite), Tank Commander and Asteroids. Here's what the original Asteroids looked like:

The IE9 test drive pages contain an SVG version called SVG-oids:

http://ie.microsoft.com/testdrive/Graphics/35SVG--oids/Default.xhtml

Have fun and (for those of us of a certain age) relive the golden age of video games!

You can tell from my score (below) that I'm a bit rusty at this:

And for a more authentic experience, have a go at this version:

http://www.play.vg/games/4-Asteroids.html

Flare has had built-in version control support for some time now - but only for Microsoft's Team Foundation Server and Visual Source Safe. If you use a non-Microsoft version control system you have to make other arrangements.

If you're a CVS or SVN user then, of course, you can just use something like TortoiseCVS or TortoiseSVN from within Windows Explorer. But in the past Madcap have pointed Flare/SVN users in the direction of the SVNSCC plugin produced by PushOK Software as a solution that allows you more or less the same functionality offered to TFS/VSS users, in terms of being able to work with a source control repository directly within Flare.

This worked OK in Flare 5. It wasn't brilliant, it was a little clunky, but it did work, and it provided real benefits. Specifically it made it easier for writers to update the repository and it made it less likely that you'd forget to get the latest version of a file before starting to work on it. Using the plugin has definitely resulted in fewer version conflicts to resolve.

Unfortunately, after installing Flare 6, try and get the latest version of files and you get this:

Unexpected exception: Access violation - KERNEL32.dll

After clicking OK, the Progress dialog box shows an error message like this:

Querying source control server. This could take several minutes.
: D:\Alistair\ITauthor\Flare-demo-project\itauthorflare\: CustomScc:GetLatestVersion - call failed with error code -15 (Nonspecific error.)

The source control operation finished with warnings and/or errors. Press Close when you are done reviewing the messages.

This is really disappointing for a number of reasons:

• I'd obviously prefer us to use the latest version of Flare rather than having to stick on version 5.
• Flare 6 has been out a few weeks now and the forum shows no positive response from Madcap or indication that they're going to fix this. Yes, I know the plugin is third-party software, but Madcap do not provide their own alternative and have, in the past, suggested SVN users use this plugin: I found out about it via Madcap.
• I had to push to get my purchase request for plugin licences signed off and right now that's looking like a bad decision. I don't want to use something else. I don't want to write off that purchase. I won't get another similar purchase signed off next time.
• I generally have a high regard for Madcap, but in this instance I feel they've let me down. Subversion is not some weird, new, little used system. If you have Microsoft blinkers on you might think that, but you'd be wrong. Subversion has been around since 2000, it's the successor to CVS and is used in software companies around the world.

For more tales of Flare/SVN woes go to: http://forums.madcapsoftware.com/search.php and search for pushok.

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.

Naturally, as is my habit, I took the first available wrong turn and very soon found myself driving around an unfamiliar Scottish seaside town in the rain.

This is why I need sat nav. And it struck me, as I was stuck at yet another set of traffic lights, that context-sensitive online help in a software application is like sat nav in a car.

You never notice how badly signposted towns are until you're lost. Then it becomes painfully obvious just how often streets don't have a street sign on them, and how road signs tell you your destination is in one direction at one junction but when you come to the next junction the destination isn't mentioned and you're left to make your best guess. Signs are often only designed for locals - so they indicate how to get to places a few miles away, but they're no use if you want to get out of town and go somewhere else.

This is like software. Poorly designed software is difficult to navigate and often only takes into account the most likely use cases. If you're doing anything even slightly out of the usual, then you're own your own mate!

Without sat nav, when you get lost, you can generally do one of two things:

1. Ask an expert
   This involves stopping the car and either asking a local, or (usually more reliable) phoning your nearest and dearest and asking him/her to look up Google Maps and work out directions for you.
2. Look up a map
   Again you've got to stop the car. You've also got to keep a road atlas in the car. And you've got to rely on it being up to date.

The software equivalent of 1, without online help in an application, is asking a colleague to help you out. This takes you away from your computer, interrupts someone else's work and requires a patient local expert. There's only so many times you can use this workaround before it gets very irritating for everybody.

The software equivalent of 2 is reading the printed manual. This assumes there is one and it's up to date. Again it disrupts the flow of your work within the application (like stopping the car to dig out the map).

Other similarities between context-sensitive help and sat nav are:

• It should be available when you want it.
• It's got to give you correct information.
• It should tell you only what you need to know.
  Verbose online help is about as irritating as a sat nav that keeps telling you to "continue straight on" rather than shutting up until it's time to turn.

Anyway, to finish, here's a Sunday-best picture of Ayr (it wasn't looking like this on Thursday).

Chances are you’re probably listening to this podcast on an iPod. And if you are, then you’ll know that you didn’t have to do anything special to get it on your iPod. You just plug the iPod into your computer now and then and new podcasts like this appear, as if by magic. All you have to do is initially choose which podcasts you want to listen to – or which video podcasts you want to watch – and click the Subscribe button. The rest of the process just happens.

Same goes for news readers. If you use Google Reader, or something like it, then you’ll know that it just gathers up blog posts, news articles and other information published on the Web sites that you’ve been interested enough to subscribe to at one time. After you subscribe to a site you don’t need to do anything else, just check Google Reader and see what new stuff shows up.

And how does this happen? Well largely through a technology called RSS. It’s been around a while now but it’s still there, doing what it does: making it easy for you to read blog posts; making it easy for you to publish information here, there and everywhere; making it easy for you to listen to podcasts like this.

So this the ITauthor history of RSS.

Introduction

I want to take you back to August 24, 1995.

• In a circus tent on their Redmond campus, Microsoft are launching Windows 95, to a soundtrack by the Rolling Stones.
  
  
  
  The Windows 95 launch party venue (above) and desktop (below)
  
  And for an additional $50 you can buy another new Microsoft product: Internet Explorer 1.0.
• AOL is the world’s largest internet access provider.
  
  
• But if you don’t want to sign up with AOL, you could try a newcomer to the online connectivity market: MSN - not the instant messaging client that would eventually inherit those initials: but the Microsoft Network.
  
  Like the market leaders (AOL, CompuServe and Prodigy) MSN is another walled-in online service. And like all of its competitors, this incarnation of MSN will suffer the same fate just as soon as people realise the alternative to these services is the full-blown, wide open world of the worldwide web.
• Before AltaVista (which won’t launch until December of this year), and long before Google, the human-powered Yahoo is the way most people find what they’re looking for on the internet.
• At the cinema, you can go and see Toy Story: the world’s first wholly computer-generated full length animation.
• IBM are about to buy Lotus Development Corporation for a cool 3.5 billion US $ in cash just to get their hands on the hugely successful Lotus Notes.
• Computer enthusiasts this year are looking forward to replacing their 14.4 kilobits per second modems with 28.8K modems later in the year, and they’re hoping soon to be able to replace their 4-speed CD-ROM drives with drives for a new kind of disks: DVDs. But they’re going to have to wait a while before those eventually get into the shops.
• Boris Yeltsin is Communist Party General Secretary in the Soviet Union.
  
   
  
• And in the White House, 21-year-old Monica Lewinsky has just started work as an intern for the Clinton administration.
  
   

And in the offices of Apple Computer at One Infinite Loop, Cupertino, California, a 30-year-old computer scientist named Ramanathan Guha, working in Apple’s Advanced Technology Group, has started developing something he’s calling MCF: the Meta Content Framework.

http://research.google.com/pubs/author17184.html
 

http://www.guha.com/mcf/mcf_spec.html

Guha described the problem he was trying to solve like this:

We use a number of different IMAs [information management applications] – browsers, email, newsreaders, file systems, etc. to manage our information. They each handle collections of information objects: web pages, images, email messages, files, folders, etc. …

Each IMA uses its own representations for these structures and provides its own utilities for viewing and manipulating them. Furthermore, the structures in use today are very simple and inexpressive. They don't allow us to represent very much about the content. The structure is typically a tree or graph with a very limited number of attributes such as the author, modification date and size …

We claim that the lack of an expressive, open standard for representing these structures is at the root of many of our information management problems. In fact, we have become so accustomed to these problems that we hardly even regard them as problems any more. For example, our information today is divided up into separate containers such as email, files, web pages, etc. This division is based not on what the content is about or which tasks they are relevant to, but on which protocol is used to access/manipulate them.

Guha, R. 1996. White paper describing MCF. http://www.guha.com/mcf/wp.html

Guha’s goal for MCF was that it would provide:

an adequate system for representing a wide range of information about content.

Guha, R. 1996. White paper describing MCF 0.95. http://www.guha.com/mcf/mcf_spec.html
         

Apple sauce

One of the first uses of MCF was something called HotSauce. This bizarrely named product never got past its beta version, but was nevertheless a typically innovative idea from Apple’s Advanced Technology Group. HotSauce used the description of a website, written in MCF, to display a representation of the website as a 3D graphic that you could navigate through: like you were steering some sort of flying vehicle in a video game. Objects in the website you were exploring were displayed as garishly coloured shapes, each bearing a label, and all set on a black background, so that it looked like the objects were floating around in outer space. The colours of the object denoted levels of depth within the website structure, and the shape of the objects indicated the type of resource. So pages and files were rectangles, whereas topic areas were lozenge-shaped.

You could move through the 3D space by pointing and clicking with the mouse, or you could reverse or go at double-speed by holding various keys while you clicked. The slogan for the product was: “Why just browse when you can fly?”

HotSauce was made available in 1996 as a standalone application and as a free plugin for Netscape Navigator and Internet Explorer. With the browser plugin installed, whenever you visited a website that was MCF-enabled, you could click a HotSauce link and the plugin could fetch the MCF file and display the 3D graphic, allowing you to fly around the site in its outer space representation. If you saw an object that interested you, you simply double-clicked it to display the page or to download the file.

http://www.ch.ic.ac.uk/ectoc/echet96/echet96_nav.html

http://en.wikipedia.org/wiki/HotSauce

An example of the HotSauce interface, showing the Sailmaker Software website. http://mundi.net/maps/maps_018/hotsauce.html

Despite Apple’s claims of having 30,000 HotSauce-enabled websites in September 1996, HotSauce was never released other than as a beta, and Steve Jobs canned the project, and closed down the Advanced Technology Group, after he returned to Apple at the end of 1996.
      

Netscape and RDF Site Summary

In February 1997, Ramanathan Guha left Apple to become Principal Scientist at Netscape Communications. Here he met Tim Bray, who had worked on the W3C's specification for XML and was, at the time, doing some consultancy work at Netscape.

http://www.textuality.com/Tim.html

Bray picks up the story:

In 1997, Guha went to work for Netscape, at about the same time as I signed up as a consultant there. Netscape was already on its way downhill, suffering from self-inflicted wounds as well as Microsoft's Netscape delenda est [Netscape must be destroyed] attitude, but neither of us knew that.

They asked me to work with the newly-arrived Guha on making something happen with MCF by combining it with XML. There were a couple of reasons. First, they … really wanted to do some things with metadata. Second, Microsoft had recently roiled the waters with the first-ever proposed standard based on XML, namely Channel Definition Format (CDF), which was going to revolutionize “push” technology which at that point was going to be the future. And Netscape wanted to look like they were in the game.

The trouble with Guha is that he's really smart, I mean extremely remarkably smart, and he thinks faster than you do, and so it's hard to figure out what he's talking about. Fortunately, he doesn't mind explaining it five or six times till you get it.

After he'd explained MCF five or six times, I kind of got it, and we cooked up something called “MCF in XML”, which Netscape then submitted to the W3C [http://web.archive.org/web/20080103080131/www.w3.org/TR/NOTE-MCF-XML/ also: http://www.w3.org/TR/NOTE-MCF-XML/], along with a tutorial. I just now glanced over those and parts of them feel remarkably prescient, others frankly ridiculous.

Since MCF was very general-purpose, it could obviously have been used to do the things CDF could be used to do, and lots more besides. Blood was running from eyeball-sockets in Redmond at this point, and a gnashing of teeth filled the hallways there, and the angst was forcibly expressed not just there but inside the W3C.

In a fairly inspired move, the W3C announced that they were going to do a general-purpose metadata thingie, and that they'd already decided that it was going to be named RDF, which had the major advantage of being neither MCF nor CDF. Working Groups were formed (I was in the RDF WG for a little while), and eventually we got RDF.

Bray, T. 2003. The RDF.net Challenge. http://www.tbray.org/ongoing/When/200x/2003/05/21/RDFNet

     
These were the days of dial-up connections, when you were charged for the length or time you stayed connected. For most people, using the internet consisted of logging in, grabbing the information you needed and logging off again as quickly as possible. These were also the days of the concerns about “information overload”. This was seen as a growing problem of the modern life.

In October 1996, Reuters conducted the first ever study into Information Overload, called Dying for information,

People can no longer develop effective personal strategies for managing information. Faced with an onslaught of information and information channels, they have become unable to develop simple routines for managing information …

The problem will not go away and those that solve it will be the success stories of tomorrow.

Waddington, P. 1997. Dying For Information? A Report On The Effects Of Information Overload In The Uk And Worldwide. Reuters.
http://www.cni.org/regconfs/1997/ukoln-content/repor~13.html

    
With more and more information becoming available on the internet, sent to you in emails and accessible in databases, how could you cope with it all? What was needed was some way of organising it all and making sure it was easy to find important information amidst an ocean of less important, or completely pointless information.

At the same time the buzzword that was getting everybody excited was “push”. The idea behind push technology was that you only had to choose what sort of information you wanted, and it would be sent to you as soon as it became available without you having to go and look for it. PointCast were the first bright stars of push technology. They launched in February 1996 to huge press interest.

However, PointCast effectively exacerbated the problem of information overload. Also, PointCast really required an always-on connection to work the way it was intended, and at the time few ordinary users had that luxury. For those who did, it stretched the limited bandwidth of their network, and soon began to annoy users as PointCast customers realised that they could use the technology to push advertising onto users’ desktops.

Articles of the time discussed the relative merits of the “push” and “pull” models – with pull being likened to the way you’d use a traditional library, where you have to put the effort into looking up and retrieving the information you’re interested in, whereas push was more like television, with content being collated for you and delivered in “channels” dedicated to specific areas of interest. All you had to do was choose the channels you wanted and the information flowed straight to your desktop.

Pointcast’s star burned brightly, if briefly. Their stock price soared. In January 1997, News Corporation would make an offer of $450 million to buy the company. But PointCast sat on the offer and a few months later it was withdrawn (a lucky escape by News Corp).

These were the days of the first browser war, and Netscape and Microsoft vied to cut a deal with Pointcast. Netscape got there first in late 1996, but the deal fell through. Then in December 1996 Microsoft announced that the Pointcast Network channels would be available the following year as a feature of Internet Explorer 4.0.

Probably the most memorable Microsoft feature that came out of push technology was Active Desktop, which was released as an upgrade to Windows 95 and Windows NT at the same time as IE4. This enabled ActiveX controls to run on the desktop, which meant that users could display news feeds and other information on their desktop: not in an Internet Explorer window but directly on the Windows desktop. The idea was that as you worked on your Windows PC, opening and closing applications, you’d be able to see up-to-the-minute news, share prices, weather reports and so on, without having to open a browser window.

By default, when you installed Active Desktop, the only thing you got was the Channel Bar. This was a strip of icons that linked to the Microsoft Network, AOL, PointCast and some standard topic channels.

The Channel Bar on the Windows "Active Desktop"

Promotion for "live content" in IE4

And you could go online and get more so-called “live content” by adding channels to your Active Desktop. Each of the channels published on your Active Desktop got there thanks to a CDF file. As Tim Bray observed in the previous quote, CDF was Microsoft’s XML-based Channel Definition Format, that had prompted Netscape to develop an XML-based version of Guha’s MCF.

Microsoft described the purpose of a CDF file as follows:

The CDF file defines a hierarchy of pages included in the channel. In addition to defining the resources in the channel, the CDF file also specifies how each item will be used or displayed, and when the channel should be updated.

Microsoft Corporation. Introduction to Active Channel Technology. http://msdn.microsoft.com/en-us/library/aa768023(VS.85).aspx

So, by the summer of 1997, it was possible to write a CDF file for your website that would allow Internet Explorer users to subscribe to your site as a channel, browse the site offline and receive an email when you updated your site.

<?xml version="1.0" encoding="UTF-8"?>

<CHANNEL HREF="http://domain/folder/pageOne.extension"

  BASE="http://domain/folder/"

  LASTMOD="1998-11-05T22:12"

  PRECACHE="YES"

  LEVEL="0">

    <TITLE>Title of your Channel</TITLE>

    <ABSTRACT>Synopsis of your channel's contents.</ABSTRACT>

    <SCHEDULE>

      <INTERVALTIME DAY="14"/>

    </SCHEDULE>

    <LOGO HREF="wideChannelLogo.gif" STYLE="IMAGE-WIDE"/>

    <LOGO HREF="imageChannelLogo.gif" STYLE="IMAGE"/>

    <LOGO HREF="iconChannelLogo.gif" STYLE="ICON"/>

    <ITEM HREF="pageTwo.extension"

      LASTMOD="1998-11-05T22:12"

      PRECACHE="YES"

      LEVEL="1">

        <TITLE>Page Two's Title</TITLE>

        <ABSTRACT>Synopsis of Page Two's contents.</ABSTRACT>

        <LOGO HREF="pageTwoLogo.gif" STYLE="IMAGE"/>

        <LOGO HREF="pageTwoLogo.gif" STYLE="ICON"/>

    </ITEM>

</CHANNEL>

IE4 contained a Subscriptions item in the Favorites menu that allowed you to subscribe to the currently displayed web page.

http://www.microsoft.com/msj/1097/activedesktop.aspx

Clicking Subscribe in this menu launched the Web Site Subscription wizard, that took you through the various options you could configure for the subscription – like the update schedule, whether you wanted to be notified by email if something in a subscription changed, and how many layers of linked pages to download when updating subscriptions to allow you to browse sites offline.

And it’s probably worth noting that, despite their reputation for not caring about standards, here was Microsoft, in 1997, developing a very early implementation of XML (prior to the publication of XML 1.0), promoting the use of XML, and submitting an open specification of CDF to the W3C in March 1997. (http://www.w3.org/TR/NOTE-CDFsubmit.html)

But let’s get back to Netscape. Remember, Netscape Navigator had been the browser most people were using to browse the Web. But Microsoft had eventually got their act together and had bought a browser, which they then steadily improved over several releases, all the while sucking market share life out of Netscape.

We heard earlier that Tim Bray had met Ramanathan Guha at Netscape, worked on an XML version of MCF, and had then been on a W3C working group to produce something similar to MCF in XML (but more specifically designed for the purpose of representing information about resources on the WorldWide Web). This was RDF: the Resource Description Framework.

Ramanathan Guha also worked on the specification of RDF for the W3C. Guha evangelised RDF back at Netscape and, as a result, RDF was used by Netscape as the means by which websites could be summarised for syndication purposes (although, at the time, while push technology seemed like it was the future, “channels” was the word most people used, rather than syndication).

Netscape used RDF Site Summary (or RSS) on its My Netscape portal. At the launch of My Netscape, in March 1999, a Netscape executive explained:

The My Netscape Network is the Web's first open portal service that empowers consumers to view all the Internet content they want in one convenient location on the Web all through My Netscape

Cyrus Afzali. March 15, 1999. Netscape Launches Publishing Program. http://www.internetnews.com/bus-news/article.php/3_80051

The idea was that My Netscape would be a customisable start page where users would spend much of their time. This page would display information – such as news headlines, stock prices and sports results – from channels chosen by the user: all made possible by Web sites publishing RDF Site Summaries.

These summaries were just short lists of links – each item on the list simply consisting of the text of the link and the URL for the link. Web site publishers could make their content available as a so-called “channel” by publishing RDF Site Summaries that internet users could add to their own customized My Netscape home page.

Here’s how Netscape announced the idea in a press release from June 1998:

Netscape Communications Corporation today announced plans to roll out "My Netscape," a free new service that will allow Internet users to create, customize and maintain a personalized start page hosted by Netscape Netcenter, one of the leading portal sites on the Net. My Netscape will provide access to up-to-the-minute news, stock quotes, entertainment and sports information through a user's custom-configured page. …

In just a few minutes, Internet users will be able to register as a Netscape Netcenter member and begin building their own personal "window to the Web." Rather than having to check dozens of different sites for the information they need everyday, users will be able to create a single, integrated access point for all their needs, saving both time and connection charges. My Netscape will take advantage of tight integration with one of the leading search engines on the Net, Netscape Search powered by Excite, as well as Netscape Communicator, the market-leading Internet client software. …

My Netscape will provide the ultimate Internet start page allowing users the freedom to choose from a wide variety of compelling content from such information categories as: automotive, computers & Internet, business, education, entertainment, games, health, kids and family, lifestyles, local news, Netscape news, headline news, personal finance, real estate, shopping, sports, travel, technology, and weather, in addition to Internet discussion groups and professional communities.

http://www2.prnewswire.com/cgi-bin/stories.pl?ACCT=104&STORY=/www/story/06-01-1998/0000670135&EDATE=

What this meant was that if you published a Web site, you could create an RDF file, make it available on your site, and submit it to the My Netscape Network. Netscape supplied the artwork for a button you could put on your web site that had the Netscape logo and the words: “Add this Site to My Netscape”. So, if visitors to your site were already signed up for My Netscape and they wanted to add your site to their home page, they could simply click the button and a little bullet-list summary of your site, regularly updated, would be added to their My Netscape page.

So RDF Site Summary was the original name that brought us the initials RSS. The definition of site summaries was done using RDF, which itself was an application of XML. So the relationship between RSS and XML was kind of grandchild to grandparent, in that RDF was a method of describing internet resources and was created as valid XML, and RSS was a way of providing summaries of Web site content and was created as valid RDF.

The version of RSS used in My Netscape in March 1999 was RSS 0.9. Versions of RSS, and the version numbering, will get a little bit tricky, so it’s worth emphasizing that this RSS, used for the original release of My Netscape, was 0.9 and it was based on the W3C-specified RDF that Tim Bray and Ramanathan Guha had been working on.

0.9 was a simple XML format that used just 10 elements to describe information about Web sites such as news sites containing collections of new stories. The document would contain a “channel” element describing the site, an “image” element to provide the logo for the site’s channel box on your My Netscape page, and up to 15 "item" elements, each of which themselves contained just a "title" element and a "link" element.
        
       

0.91: RSS becomes Rich Site Summary

The primary author of RSS 0.9 was a young programmer called Dan Libby, working in his first job out of university. Here he describes the troubled birth of RSS, at a troubled Netscape:

The original RDF/RSS spec was deemed "too complex" for the "average user".

…  My (poor) solution was to create a simpler format, RSS 0.9, that was technically valid RDF, but dropped namespaces and created a non-connected graph.

… We shipped the first implementation, sans tools.  Basically, there was a spec for RSS 0.9, some samples, and a web-based validation tool.  No further support was given for a while, and I was kept busy working on other projects.  Even still, channels started coming in, and the system worked in a rudimentary fashion.
At some point, it was decided that we needed to rev the RSS spec to allow things like per item descriptions, i18n support, ratings, and image widths and height.  Due to artificial (in my view) time constraints, it was again decided to continue with the current storage solution, and I realized that we were *never* going to get around to the rest of the project as originally conceived.  At the time, the primary users of RSS (Dave Winer the most vocal among them) were asking why it needed to be so complex and why it didn't have support for various features, eg update frequencies.  We really had no good answer, given that we weren't using RDF for any useful purpose.

… The compromise was to produce RSS 0.91, which could be validated with any validating XML parser, and which incorporated much of userland's vocabulary, thus removing most (I think) of Dave's major objections.  I felt slightly bad about this, but given actual usage at the time, I felt it better suited the needs of its users: simplicity, correctness, and a larger vocabulary, without RDF baggage

http://tech.groups.yahoo.com/group/syndication/message/586

Dan Libby
http://osc.co.cr/aboutus/aboutus.html?menubar=aboutus
      

The important point to note about Dan Libby's work on RSS 0.91 was that he removed RDF from RSS at this point. So what about the name? How can you have something called RSS, standing for RDF Site Summary, when it doesn’t contain the RDF any more?

The solution Libby came up with was to rechristen the 0.91 release: Rich Site Summary – which was justified by the new features that had been incorporated, as Libby says: “from UserLand’s vocabulary”.

So at this point in the RSS story we need to bring in UserLand Software and it’s controversial founder, Dave Winer. I’ve held off talking about Dave Winer up until now just to try not to muddy the waters. But we can’t hold off any more, so – from 1999, where we’ve reached so far – let’s rewind a little and consider Winer’s role in the story.
     
        

Dave Winer and <scriptingNews>

UserLand was a California-based software company started by Dave Winer in 1988. Its original product was a scripting environment for the Apple Macintosh called Frontier, with a scripting language called UserTalk. However, Apple destroyed the original market for Frontier by bundling its own scripting language, AppleScript, with new Macs. So UserLand had to find a new line of business and eventually settled on Web publishing tools and services. Along the way, in 1997, Winer started publishing regular, date-stamped posts of his thoughts on a variety of subjects at a Web site called Scripting News. At the time there wasn’t a word for this type of Web site – personal opinions, seemingly random note-form snippets of information, liberal use of links to other sites – but by the end of this year (1997) a name had been coined: weblog, soon shortened just to blog.

Scripting News is generally regarded as one of the first blogs. And as of today (March 2010) Dave Winer is still posting to scriptingnews.com, which probably makes it the world’s longest running blog. And to look at it you can easily believe it’s antiquity: it still looks like something right out of 1997.

http://commons.wikimedia.org/wiki/File:Dave_Winer.JPG. Copyright: http://commons.wikimedia.org/wiki/User:Helge.at
licensed under the Creative Commons Attribution ShareAlike 2.5, Attribution ShareAlike 2.0 and Attribution ShareAlike 1.0

Back in 1997 XML was still in its infancy. XML 1.0 hadn’t yet been recommended by the W3C and XML wasn’t really being used for anything much yet. But that was about to change in a big way. Like never before, by 1997, systems needed to pass data around, quickly, from one system to another, across the room or around the world, flawlessly, irrespective of hardware or operating system. XML was a standard, text-based method of describing data, that could be endlessly extended to cover pretty much any type of information. Dave Winer was fascinated by the idea and its potential.

In mid December 1997, he wrote in Scripting News:

Everyone talks in hushed tones about XML. Shhh. It's exciting! But what does it do?

I can't get involved with something without immediately trying to ground it with an application. How else could I know if it's worth exploring?

Luckily, I had an application waiting for XML.

http://www.scripting.com/davenet/1997/12/15/realWorldXml.html

Winer’s application was a script that ran every night at midnight and produced a file called siteChanges.xml. The file described any new pages on the Web site, or pages that had been modified in the last 24 hours. Winer’s XML wasn’t RSS, but the XML file served a very similar purpose to the RSS files that, in the future, would list the most recent posts from a blog or stories from news sites.

A few weeks later, just before New Year, in one of his regular DaveNet newsletter emails – a posting that ends by asking readers if they know of any good New Year's parties – Winer mentions that the Scripting News Web site:

in addition to being an HTML web page, is also an XML application

http://www.scripting.com/davenet/1997/12/15/scriptingNewsInXML.html . Note: this post is dated as 15 December although it says in the post that it is between Christmas and New Year

What Winer meant was that as well as publishing a standard Web page, from now on he was also making the front page of the Web site available as an XML file. He wrote a script called scriptingNewsToXML that generated an XML file for that day’s posting on the site. The top-level element in this XML file was called <scriptingNews> (all one word) – so <scriptingNews> became the de facto name for this new application of XML.

Basically the <scriptingNews> XML format consisted of a bunch of header elements followed by a list of “item” elements, each of which could contain “text” elements and “link” elements, and that was pretty much it. But that was enough to describe what you could find if you went to the Scripting News Web site: each item represented a blog post and could contain multiple links (not just a link to the original blog post). In other words, the <scriptingNews> XML format provided everything a developer needed to produce real summaries of Web site content – not just links back to the article itself: these summaries could be consumed in their own right, and they might be all you needed – that is, you might not need to display the site itself.

Remember, this is December 1997. For a few months now, Microsoft has been using its Channel Definition Format (CDF) to allow you to see “live content” on your Windows 95 Active Desktop, and to let you subscribe to CDF-enabled Web sites in Internet Explorer, meaning you could then browse those sites offline. But Netscape’s launch of their My Netscape portal, which used RDF Site Summary (the original technology to bear the name RSS), was still more than a year away.

Winer has often been called the inventor of RSS. He would certainly go on to play a major part in the development of RSS, but back then, when Winer announced the XML version of his blog (before the appearance of RSS), it’s hard not to see Microsoft’s CDF as being the first application of XML to allow people to subscribe to Web content. Certainly Winer was well aware of CDF and there are many similarities between CDF and the <scriptingNews> XML format.

The following is an example of the original <scriptingNews> format. This is the XML for the Scripting News entry for 7 July 1998.

<?xml version="1.0"?>

<!DOCTYPE scriptingNews SYSTEM "http://www.scripting.com/dtd/scriptingNews.dtd">

<scriptingNews>

  <header>

    <copyright>Copyright 1997-1998 UserLand Software, Inc.</copyright>

    <scriptingNewsVersion>1.0</scriptingNewsVersion>

    <pubDate>Fri, 07 Aug 1998 07:00:00 GMT</pubDate>

    <lastBuildDate>Sat, 08 Aug 1998 12:01:07 GMT</lastBuildDate>

    <docs>http://www.scripting.com/frontier5/xml/scriptingNews.html</docs>

    </header>

  <item>

    <text>Douglas Adams:  "His opinions are passionately held, well-informed, intelligent, argumentative 
and quite often wrong."</text>

    <link>

      <url>http://www.userland.com/slideshows/daveNetReaderProfiles/slide14.html</url>

      <linetext>Douglas Adams</linetext>

      </link>

    </item>

  <item>

    <text>XML-related changes coming in Frontier 5.1.3.</text>

    <link>

      <url>http://www.scripting.com/frontier5/xml/stories/513changes.html</url>

      <linetext>XML-related changes</linetext>

      </link>

    </item>

  <item>

    <text>Today's Scripting News XML file.  There's one file for every day that we publish. Josh Lucas's 
nightly mailing of Scripting News is based on this feature, as is Vignette's experimental StoryServer 
displayer.</text>

    <link>

      <url>http://www.scripting.com/98/08/news07.xml</url>

      <linetext>Today's Scripting News XML file</linetext>

      </link>

    <link>

      <url>http://www.stonecottage.com/josh/scriptingNews.html</url>

      <linetext>mailing</linetext>

      </link>

    <link>

      <url>http://www.scripting.com/frontier5/xml/experiments/scriptingNews.html</url>

      <linetext>feature</linetext>

      </link>

    <link>

      <url>http://demo.vignette.com/publishing/scriptingnews/</url>

      <linetext>StoryServer displayer</linetext>

      </link>

    </item>

  <item>

    <text>Tallent: Frontier ODBC Extension 1.0b8. &lt;i>Mac and Windows.&lt;/i></text>

    <link>

      <url>http://www.tallent.com/frontier/odbc/</url>

      <linetext>Frontier ODBC Extension 1.0b8</linetext>

      </link>

    </item>

  <item>

    <text>Seth Dillingham on List-based support.</text>

    <link>

      <url>http://betty.userland.com/stories/daveWiner/98/08/dillinghamOnListBasedSuppo.html</url>

      <linetext>Seth Dillingham</linetext>

      </link>

    </item>

  <item>

    <text>Fat Page: scriptingNewsToXML.</text>

    <link>

      <url>http://www.scripting.com/fatPages/websites/scriptingNewsToXML.html</url>

      <linetext>scriptingNewsToXML</linetext>

      </link>

    </item>

  <item>

    <text>News.com: Web technologies usurp DCE. IMHO, eventually this will become the XML-RPC 
story.</text>

    <link>

      <url>http://www.news.com/News/Item/0,4,25043,00.html?st.ne.fd.mdh</url>

      <linetext>Web technologies usurp DCE</linetext>

      </link>

    <link>

      <url>http://www.scripting.com/davenet/98/07/xmlRpcForNewbies.html</url>

      <linetext>story</linetext>

      </link>

    </item>

  <item>

    <text>News.com missed something. Microsoft's COM is an implementation of DCE. It has more momentum 
than they thought.</text>

    <link>

      <url>http://www.microsoft.com/presspass/press/1996/sept96/dcompr.htm</url>

      <linetext>COM is an implementation of DCE</linetext>

      </link>

    </item>

  <item>

    <text>Reuters: Eudora security flaw discovered.</text>

    <link>

      <url>http://www.zdnet.com/zdnn/stories/zdnn_smgraph_display/0,3441,2126115,00.html</url>

      <linetext>Eudora security flaw discovered</linetext>

      </link>

    </item>

  <item>

    <text>http://www.webstandards.org/.</text>

    </item>

  <item>

    <text>SJ Merc: Here's a great picture of Microsoft's Steve Ballmer having a strong physical reaction 
to something Becky Morgan said. Here's the rest of the story...</text>

    <link>

      <url>http://www.sjmercury.com/business/microsoft/media/photos/ballmer080798.jpg</url>

      <linetext>picture</linetext>

      </link>

    <link>

      <url>http://www.sjmercury.com/business/microsoft/docs/move080798.htm</url>

      <linetext>story</linetext>

      </link>

    </item>

  <item>

    <text>Our friend Thea is looking for mind-blowing  Frontier projects that she can showcase in her 
Galleria. &lt;i>A great flowbuilder!&lt;/i></text>

    <link>

      <url>mailto:thea@yes.net</url>

      <linetext>Thea</linetext>

      </link>

    <link>

      <url>http://www.scripting.com/thea/</url>

      <linetext>Galleria</linetext>

      </link>

    </item>

  <item>

    <text>Douglas Adams on his nose.</text>

    <link>

      <url>http://www.tdv.com/personal_worlds/douglas_a/nose/nose.html</url>

      <linetext>his nose</linetext>

      </link>

    </item>

  </scriptingNews>

http://www.scripting.com/98/08/news07.xml

        
The DTD for <ScriptingNews> looked like this:

<!ELEMENT scriptingNews (header, item+)>

<!ELEMENT header (copyright, scriptingNewsVersion, pubDate, lastBuildDate, docs)>

<!ELEMENT copyright (#PCDATA)>

<!ELEMENT scriptingNewsVersion (#PCDATA)>

<!ELEMENT pubDate (#PCDATA)>

<!ELEMENT lastBuildDate (#PCDATA

<!ELEMENT docs (#PCDATA)>

<!ELEMENT item (text, link*)>

<!ELEMENT text (#PCDATA)>

<!ELEMENT link (url, linetext)>

<!ELEMENT url (#PCDATA)>

<!ELEMENT linetext (#PCDATA)>

http://www.scripting.com/dtd/scriptingNews.dtd

      
And this is the RSS 0.9 DTD created by Dan Libby:

<!ELEMENT rdf:RDF (channel | image? | item+ | textinput?)*>

<!ATTLIST rdf:RDF

xmlns:rdf CDATA #FIXED "http://www.w3.org/1999/02/22-rdf-syntax-ns#"

xmlns     CDATA #REQUIRED> <!-- must be "http://my.netscape.com/rdf/simple/0.9/"> -->

<!ELEMENT channel (title | description | link)*>

<!ELEMENT title (#PCDATA)>

<!ELEMENT description (#PCDATA)>

<!ELEMENT link (#PCDATA)>

<!ELEMENT image (title | url | link)*>

<!ELEMENT url (#PCDATA)>

<!ELEMENT item (title | link)*>

<!ELEMENT textinput (title | description | name | link)*>

<!ELEMENT name (#PCDATA)>

http://www.rssboard.org/rss-0.9.dtd

      
Winer did nothing much with the <scriptingNews> XML format during 1998, which brings us back to 1999 again, with the launch of My Netscape in March, and it’s RDF Site Summary XML format: RSS 0.9.

Winer was excited by what Netscape had done, and no doubt pleased to have been ahead of the curve – but he was disappointed that Netscape hadn’t given RSS 0.9 at least the same functionality of the <scriptingNews> XML format. He wrote:

RSS is woefully inadequate. It's missing the key thing web writers and readers need. A channel is not a series of links pointing to articles, it's a set of paragraphs that point to one or more articles *per paragraph*. …

Writing happens in paragraphs. Web writing allows links to be anywhere. To limit channels to one link per paragraph is not good! Technology serves writers and readers, they shouldn't be limited by technology.

http://www.scripting.com/davenet/1999/06/16/aFaceOffWithNetscape.html

Winer got in touch with Netscape and tried to influence the direction of the next version of RSS. Winer says Netscape promised to incorporate the good stuff from <scriptingNews> into RSS, but Winer was obviously not convinced because he went away and revised <scriptingNews>, to produce the description language he was looking for.

The original <scriptingNews> format had contained just 12 elements. Version 2.0b1 had more than twice that number of elements: all of the new elements appearing within the header element.

The new elements included:

• channelDescription
• managingEditor and webmaster (for contact emails) and
• skipHours and skipDays to indicate to the aggregator software, that went looking for updates, that the site wouldn’t be updated over those hours or days, so it needed bother come looking for updates.

<?xml version="1.0"?>

<scriptingNews>

  <header>

    <copyright>Copyright 1999-2010 UserLand Software, Inc.</copyright>

    <scriptingNewsVersion>2.0b1</scriptingNewsVersion>

    <pubDate>Sun, 16 Nov 2003 08:00:00 GMT</pubDate>

    <lastBuildDate>Sun, 16 Nov 2003 14:06:38 GMT</lastBuildDate>

    <docs>http://my.userland.com/stories/storyReader$11</docs>

    <channelDescription>It's even worse than it appears.</channelDescription>

    <channelLink>http://essaysfromexodus.scripting.com/</channelLink>

    <channelTitle>Scripting News</channelTitle>

    <imageLink>http://essaysfromexodus.scripting.com/</imageLink>

    <imageTitle>scriptingNews</imageTitle>

    <imageUrl>http://essaysfromexodus.scripting.com/picture$29</imageUrl>

    <imageHeight>36</imageHeight>

    <imageWidth>74</imageWidth>

    <imageCaption></imageCaption>

    <managingEditor>dave@userland.com (Dave Winer)</managingEditor>

    <webmaster>dave@userland.com (Dave Winer)</webmaster>

    <language>en-US</language>

    <skipHours>

      </skipHours>

    <skipDays>

      </skipDays>

    </header>

  <item>

    <text>This is the archive of the Manila version of Scripting News that was on Exodus between the end 
of 1999 and November 2003.</text>

    </item>

  <item>

    <text>This page is an index to other resources on the new system.</text>

    </item>

  <item>

    <text>1. Place to upload graphics.</text>

    <link>

      <url>http://scriptingarchivedata.scripting.com/pictures/edit/newPicture</url>

      <linetext>Place to upload graphics</linetext>

      </link>

    </item>

  </scriptingNews>

http://essaysfromexodus.scripting.com/xml/scriptingNews2.xml

Below, a “channel” box showing items from the Scripting News blog. This is produced using RSS 0.91:

The same “channel” generated from <scriptingNews> 2.0b1:

http://my.userland.com/stories/storyReader$11
      

0.91 again: Winer's version

So now, in the summer of 1999, we had RSS 0.91 (Dan Libby’s Rich Site Summary) and Dave Winer’s <scriptingNews> 2.0b1. There was also Microsoft’s CDF which had been around for a while now, and was used for subscribing to web sites from within Internet Explorer. And IE5 (released in March 1999) introduced the idea of Smart Offline Favorites, which allowed users to mark web pages as favorites and then view those pages offline at their leisure. This was useful when you were charged for the time you spent online, but subsequently became pointless once the world switched to always-on connections. CDF was supported in Internet Explorer right up until IE7, when it finally disappeared.

And for a while not a lot happened. Dave Winer wrote:

After RSS 0.91, we breathed a sigh of relief that lasted almost a year. Glad that's over!

http://www.scripting.com/2000/06/07.html#rss

     
In December 1999 UserLand shipped its Manila content management system with built-in support for <scriptingNews> 2.0b1, but Winer had decided to drop <scriptingNews> in favour of one common XML format. And in April 2000, UserLand added built-in support for RSS 0.91 for all Manila web sites.

UserLand was one of the few organisations using RSS actively, and Winer wanted to make some changes to RSS. The problem was that RSS wasn’t changing to meet his changing needs (http://scripting.com/2000/06/07.html#rss).

But the creators of RSS 0.91, Netscape – now part of AOL – were busy working on Netscape 6 and weren’t interested in doing anything with RSS. Eventually, in early June 2000, Winer had had enough, so he decided to go ahead and make the changes himself.

He published a new spec for RSS 0.91, announcing it in a post on his Scripting News blog:

RSS 0.91 was a major traffic accident that turned out pretty well. Netscape did a private spec, just for their own web service. I had a couple of problems with it.   …

So all this is is a cleanup. All the Netscapeisms are removed. It's better organized and easier to follow.

… there is no room to debate new features, because the spec doesn't attempt to add any.

http://scripting.com/2000/06/07.html#rss

       
Winer considered calling this a spec for RSS 0.92, but – because of the cleanup nature of the revision – decided to stick with the existing revision number: 0.91.

Having two (albeit very similar) versions of RSS 0.91 was confusing. Worse though, in many people’s minds, was the fact that Winer had put a copyright notice on his 0.91 spec copyrighting it to UserLand Software.
      

1.0: Return to RDF

There was clearly a need to extend RSS, now that people were really starting to use it on their websites. Web sites like the Motley Fool financial website wanted to add elements to their RSS feeds for their own purposes (for example, an element to house the stock symbol for a listing), but there was disagreement about how this kind of thing should be done.

In an article on the O’Reilly xml.com website in July 2000, Rael Dornfest summarized the position of RSS:

RSS is going to have to evolve or die as it gets pulled in different directions. If it can't support the directions required by different developers, it will fade in favor of more special purpose formats.
…
RSS has seen a large degree of adoption from independent content producers, yet has failed to grab the attention of mainstream content providers. Perhaps the high eyeball/effort ratio message just hasn't been delivered. Or is it the "terminal beta" feel of RSS with its < 1.0 versioning that makes anyone but early adopters nervous?
…
RSS also needs more "killer apps,"
…
Scalable extensibility is a must if RSS is to continue being re-purposed. Yet this extensible RSS must remain relatively simple (somewhere between HTML and hard-core RDF should do!) …

http://www.xml.com/pub/a/2000/07/17/syndication/rss.html

      
Dornfest took up his own challenge and in August 2000, together with a group of like-minded individuals (including Ramanathan Guha), he proposed that a spec should be developed for RSS 1.0. http://tech.groups.yahoo.com/group/syndication/message/372

He also announced the RSS-DEV mailing list. The design goals of the RSS-DEV working group were:

The modular extension of existing RSS through XML Namespaces and RDF
stressing backward compatibility with RSS 0.9 for ease of adoption
by existing syndicated content producers.

http://tech.groups.yahoo.com/group/rss-dev/

   
The RSS 1.0 spec was published in December 2000:
http://web.resource.org/rss/1.0/spec

It was an attempt to get RSS back on the RDF track, after it’s detour away from RDF with Dan Libby’s modifications for Netscape’s RSS 0.91.

But perhaps the main result was just more confusion because, while RSS 1.0 was backwards compatible with RSS 0.9, it was not compatible with either of the 0.91 versions.
     

0.92: Enclosures

Dave Winer added to the version numbering fun by publishing RSS 0.92 two weeks after the publication of RSS 1.0.

RSS 0.92 was significant in a number of ways. Character limits were removed, meaning, for example, a description could be just as descriptive as it needed to be. Every child element within the item element now became optional. And the four new elements were also optional, meaning that a 0.91 file was also a valid 0.92 file.

http://backend.userland.com/rss092

Of those four new elements, one would lead to a whole new use for RSS.

This was the enclosure element. Writing in 2003, Dave Winer explains the enclosure element like this:

Like the enclosure of an email message, an RSS item enclosure is something big that may take a long time to download, or something binary that isn't text you read. You can read the text that describes the enclosure, or the enclosure may somehow be related to the item.

An example. Suppose a news source, like the NY Times runs a movie review. It might make sense to enclose a trailer for the movie along with the review. Or a band might use RSS to keep their fans informed of what they're up to. An enclosure could include a bit of music to illustrate a point.

The cool thing about enclosures is that they can be time-shifted. The aggregator or news readers should not download the enclosure until the computer is idle, and should not present the item with the enclosure to the user until the enclosure has been downloaded and is resident on the local hard disk. The key premise is No More Click-Wait.

http://cyber.law.harvard.edu/rss/enclosuresAggregators.html

However, back in December 2000 the full usefulness of enclosures in RSS was still a fairly vague dream in the minds of a handful of people, and the importance of this addition to RSS would remain unrealised for a few years yet.

There was now a period of relative quiet for RSS, in which the 0.92 version became very widely used, and millions of RSS feeds were published, around the world, using this format, allowing people to access regularly updated information, without having to browse the web. Information from the sites they subscribed to simply appeared, automatically, collected together in their feed reader of choice. Dave Winer discussed an 0.93 version with some small modifications, such as allowing multiple enclosures within an item element, but this version never appeared.

Feedreader application circa 2001

Syndirella feed reader, 2003

NewzCrawler feed reader, 2002

weblogs.com

During 2001 Winer made an important, and ingenious, change to his weblogs.com blog indexing site. The site had been using a script to go out and check for newly updated blog feeds and index them. However, by 2001 there were already a lot of blogs out there and it was becoming impractical to go out looking for changes on all those RSS feeds. So Winer turned the process around and the server that hosted weblogs.com now became a “ping server”. This meant that the server used a very basic function available to all servers: the ability to receive and record pings (that is, tiny messages sent from one computer to another, originally designed to check if the computer at the other end was running and responding). Instead of a service that has to go out and check whether feeds have been updated, the idea of a ping server was that the sites would tell the server when a feed had been updated. When the weblogs.com server received a ping it would flag up to anyone subscribing to the service that that feed had been updated. This allowed weblogs.com to serve as a central repository of information about new, and newly updated, RSS feeds, and it, in turn, was used by popular blogging services like Technorati and Feedster. The service became very popular with bloggers trying to make their blogs visible to a wider audience, and before too long weblogs.com would be getting over a million pings per day.

2.0: Rich Site Summary

The following year, in August 2002, Winer published the spec for RSS 2.0. Again this spec was copyrighted to UserLand Software. Prior to its publication, the spec had been developed using the version number 0.94, and, as this suggests, it was an evolutionary variation on the popular 0.92 spec.

One important change, however, was that the spec allowed for extension of RSS with elements that weren’t defined in the spec, provided those elements were associated with a namespace.

As of Dan Libby’s 0.91 version, RSS had stood for Rich Site Summary. The 2.0 spec now stated that RSS stood for Really Simple Syndication. This made sense as, by 2002, RSS wasn’t really about summarising a website any more – it was much more a way of allowing your newly published content to be republished in an unknowable number of places and contexts: perhaps within a stream of information in someone’s personal news reader or maybe on some other web page alongside information from similar sites to yours.

Sites quickly began to switch from 0.92 to the new 2.0 version, and RSS 2.0 became the most popular format for blog feeds. In November 2002, The New York Times showed that RSS had really started to be part of the internet mainstream when it extended its use of RSS, to allow its readers to subscribe to news feeds on a wide variety of topics.

http://phx.corporate-ir.net/phoenix.zhtml?c=105317&p=irol-newsArticle&ID=593901

Winer left UserLand Software around the time of the initial publication of RSS 2.0 in 2002. The following year he became resident fellow at the Harvard Law School's Berkman Center for Internet & Society. In July 2003 he published a 2.0.1 version of the spec and assigned the copyright to the Berkman Center. It was then made available for use under a Creative Commons licence.

Winer wanted RSS 2.0 to be something that was now set in stone and couldn’t be changed. The reason for this was that he wanted “to foster growth in the market that [was] developing around it, and to clear the path for innovation in new syndication formats.” http://www.rssboard.org/rss-specification#roadmap

Winer’s increasingly dominant version of RSS was therefore, for all practical purposes, frozen.
      

Atom

On the 16 June 2003, Sam Ruby, a software developer at IBM, wrote a blog post called “Anatomy of a Well Formed Log Entry”, including a link to a wiki he’d set up for the purpose of discussing what a standard blogging format should look like.

The wiki quickly became a rallying point for people who were keen to see some development of RSS (now frozen at 2.0).

One of the supporters of this effort was Tim Bray (who had worked with Ramanathan Guha at Netscape back in 1997 and had been on the RDF Working Group). Bray described the reasons for working on this new project:

• Firstly, there were too many versions of RSS, and confusion over which one should be used
• Next, it seemed unlikely, to say the least, that it would be possible to bring together the various factions, who had opinions about RSS, to produce a new, merged RSS version. Bray wrote:
       
  "the interested parties have a track record of inability to get along and work things out and make progress. To the extent that in some circles “RSS” has become a synonym for “Reliably Spiteful Squabbling."
  http://www.tbray.org/ongoing/When/200x/2003/06/23/SamsPie
• Bray believed that the RSS 2.0 spec was “significantly underspecified”, which led to a variety of problems – for instance, the title element in RSS 2.0 might contain HTML or it might be plain text, but there was no easy way for an RSS application like a blog aggregator to know which type was being used.
• Finally, there was a feeling that the technology surrounding RSS had matured (even if some of the personalities involved hadn’t) and a large enough community had developed with a good understanding and agreement about the problems that needed solved.

What evolved out of Sam Ruby’s wiki was originally called “pie” (with the intention that it should be as easy as …), but was then also known as “echo” for a while – until finally the name “atom” was settled on.

Atom was specifically intended to support blogs. It did pretty much exactly what RSS 2.0 did, but was designed to be more flexible.

Here’s Tim Bray on the similarities between Atom and RSS 2.0:

SOUND CLIP OF:
“So what is Atom. If you know RSS 2, Atom is really, really, really like RSS 2.”
http://itc.conversationsnetwork.org/shows/detail1155.html# 20.35 mins

Initially, in 2003, there was lots of excitement and noise about Atom. Dave Winer seemed to have an uncanny knack of sparking off flame wars on a regular basis, and there were a lot of people who were contributing to the Atom debate at least partly because it promised an RSS-type solution that had nothing to do with Winer.

The development of a spec for Atom continued, and things gradually quietened down, and as 2004 wore on RSS 2.0 continued to establish itself.

By 2004, enthusiasm for Atom had already quietened down (http://itc.conversationsnetwork.org/shows/detail260.html# ~57 mins)

However, Atom had many influential friends.

In February 2003 the blogging tool Blogger had been bought by Google. Blogger had been co-founded by Evan Williams, who went on to start up the podcasting directory Odeo, before creating the phenomenon that is twitter.

In January 2004 Google added Atom support to Blogger, allowing its million-plus users to generate feeds that could be aggregated by Atom-enabled feed readers. Blogger’s support for Atom was a huge boost to the adoption of the new format, but RSS 2.0 was used by Yahoo, by Microsoft on parts of their website and by a host other major websites and publishing tools.

The Atom 1.0 spec was eventually published in December 2005:
http://www.ietf.org/rfc/rfc4287.txt

In October 2006 IE7 was released with support for RSS, but not Atom. Within IE7, when you visited a site with RSS feeds, a little orange RSS icon lit up on the toolbar. Clicking this gave you a selection of links to the feed pages, from where you could click to add the feed to your own personal list of RSS feeds, which you accessed within the Favorites panel.

RSS 2.0 is generally considered to have won the war of the feed formats. Atom is probably a superior format in many ways but, just like the VHS/Betamax battle of the 1980s, the technically superior challenger doesn’t always win. However, unlike VHS and Betamax, there didn’t have to be a winner. Aggregators support both formats just fine and users don’t need to choose – in fact users don’t even need to know whether the site they’ve subscribed to uses Atom or RSS.

For consumers, a more interesting topic in 2004 was something that had been happening as a result of the introduction of the enclosure element into RSS.
          

The birth of podcasting

In an article from July 2003 Dave Winer describes the use of enclosures:

Adam Curry is a television personality with several weblogs and his own reality show called Adam's Family. He was also one of the first video jocks on MTV in the 1980s. He was the guy with the fantastic hair, and great sense of humor.
Adam uses a weblog tool that allows him to include an enclosure on any item.   …

Now, on the receiving end, I have subscribed to Adam's feed in my news aggregator. In its hourly scan, the aggregator notes that there's a new item that has an enclosure. It adds the information about the enclosure to a table it's keeping, of enclosures that have not yet been downloaded.

When I'm finished for the day I leave my computer on. I like to have my aggregator check new feeds every hour even when I'm not there, and I also like to give it a chance to download enclosures so the clips that Adam creates will ready for me to watch when I arrive at work early the next morning.

Sure enough, yesterday Adam released a new installment of his reality show, and the QuickTime movie, all 34 megabytes of it, is on my hard drive, just waiting for me to watch. There's a note on the desktop website home page alerting me to its existence. I fill up my cup of coffee and then sit down to watch the latest from Adam's family in the Netherlands.

http://cyber.law.harvard.edu/rss/enclosuresAggregators.html

In October 2003 Christopher Lydon interviewed Adam Curry. Curry talks about how RSS could be used to solve the bandwidth problem for consuming media files via the internet:

http://blogs.law.harvard.edu/lydondev/2003/10/03/connecting-the-dots-with-adam-curry/
16.29–18.02 mins - ends: “ands that’s a huge success”

A year later (12 October 2004), in an interview with Doug Kaye on IT Conversations, Curry describes the birth of his iPodder script in more detail:

SOUND CLIP OF:
http://cdn.itconversations.com/Adam%20Curry%20-%20Behind%20the%20Mic.mp3 
31.48–35.06 mins

The enclosure element that made all of this possible had actually been part of RSS since the publication of the 0.92 spec in December 2000. Curry was one of several people who had talked to Winer during that year about adding an element that would allow audio and video files to be referenced in an RSS feed in such a way that it would be easy for users to retrieve these files from within their feed aggregator.

So the enclosure element was in there, in 0.92, but hardly anyone ever used it, and many people didn’t even become aware of it until RSS 2.0. Here’s IT Conversations founder Doug Kaye talking in August 2006:

http://news.conversationsnetwork.org/shows/detail1192.html# 
6.12–7.10 mins, ending: “that was the early days”

But a select few had been doing things with RSS and audio files prior to 2004.

For example, in summer 2003, Stephen Downes created an application he called Ed Radio that collected links to MP3 files from RSS feeds and published them as a playlist on WebJay, a website for creating and playing collections of audio files.

Dave Winer himself was another early user of the enclosures element. From early 2001 he started testing the use of enclosures by publishing an RSS feed containing a different Grateful Dead track every day or so:

http://cyber.law.harvard.edu/rss/examples/sampleRss092.xml

Then, in 2003, Winer put together an RSS feed containing a collection of recordings of technology interviews done by his friend and colleague at the Berkman Center, Christopher Lydon (http://blogs.law.harvard.edu/lydondev/all-the-lydon-interviews-in-one-download/). We heard a clip from Lydon’s interview with Adam Curry a little earlier.

So the enclosure element had been used, but Adam Curry had two ideas that were key to making media file delivery via RSS really work:

1. Don’t just present the user with a link that they click on to download the file then and there – and wait ... and wait ... for the file to start playing – instead, get the file on the sly, in the background, drip by drip, and then (and only then) tell the user about it so that they can listen to it or view it without any delay.
2. Take the downloaded file and put it straight onto the user’s portable device, so that it just appears there without the user having to do anything other than connect their MP3 player to their computer.

When audioblogging (as it was then called) started to take off (with shows like Dave Winer’s “Morning Coffee Notes” and then Adam Curry’s hugely popular “Daily Source Code”) the first of these points, downloading the media files, was handled by an application like Radio, UserLand’s blogging software. Getting the files onto your MP3 player was generally left up to you.

Adam Curry had written a script to perform the second task, getting the files onto his iPod, and several other, more fully featured programs appeared during 2004 to do this job.

But for most people, it wasn’t until Apple embraced podcasting that these 2 functions really came together seamlessly. Podcast support was introduced into the desktop iTunes application with iTunes 4.9 in June 2005, and quickly became the most commonly used way of getting podcast files onto the world’s most popular portable MP3 device, the iPod.

The term “podcasting” first appeared early in 2004. The first published use of the word seems to have been in The Guardian newspaper in an article called “Audible revolution” published in February 2004. The name podcast – a combination of “broadcast” and “iPod” – reflects the total dominance of the iPod in the MP3 player market, a dominance gained almost from the day it was launched, back in October 2001.

Advertisement for the first iPod, launched October 2001
     

Will the real Podfather please stand up?

There has been some debate about who created podcasting. It’s a fairly pointless debate. However, it’s clear that the drip-feed/watch-it-when-it’s-downloaded idea was Adam Curry’s.

In a DaveNet article entitled “Virtual Bandwidth” from October 2000 Winer writes:

In New York I spent the better part of two days brainstorming with Adam Curry, former MTV video jock, Internet advertising entrepreneur, and now a man obsessed with a vision that I'm beginning to understand.

http://www.scripting.com/Davenet/2000/10/31/virtualBandwidth.html

Then in January 2001, in a post titled “Payloads for RSS”, Winer writes:

When I started talking with Adam late last year, he wanted me to think about high quality video on the Internet, and I totally didn't want to hear about it. Like a lot of people, I had tried it, and found it unsatisfying and frankly, exhausting.
I thought that video on the Internet was a loser for three reasons, that build on each other:

1. When I click on a link to view some video, I have to wait.
2. The wait is longer than the video. (In other words I have to wait two minutes for ten seconds of video.)
3. The quality is horrible.

All three effects are bad, but the first is the worst. The Internet lifestyle is frenetic. There's no time to wait. The remaining two negatives only make video less attractive, but the first is the killer.

But Adam persisted and showed me that if I was willing to change my point of view, it could work, without any waiting and with very high quality.

What if, in the middle of the night, while I'm not using my computer, it downloads huge video and audio stuff to my local hard drive. …

Let's see what happens with 1, 2 and 3 in this scenario.

1. When I click on a link to view some video, it starts playing immediately, because it is already on my local disk.
2. The wait is zero.
3. The quality is limited by the size of my local disk, not by the capacity of my connection.

What's different about this system is that you subscribe to channels instead of clicking-and-waiting.

http://web.archive.org/web/20010202144800/www.thetwowayweb.com/payloadsForRss

Conclusion

RSS has been one of the technologies that has helped make the internet a worldwide publication system that, every minute of every day, brings information and entertainment to the world. From an impossibly vast ocean of information on the internet, RSS makes it possible for us to divert a river of news that we can dip into as and when we want. It lets us subscribe to email notifications of blog posts, and it lets us write a message once and have it appear on our blog, on Facebook, in twitter and elsewhere. It allows us to watch or listen to programs on our mobile devices when we’re on our way to work or at the gym or in the supermarket. It was one of the first successful applications of XML and yet for most web users it’s completely invisible.

And without RSS you wouldn’t be listening to this now.

Where are they now?

So what happened to the main players in the development of RSS?

Ramanathan Guha

is reported to have walked away from $4 million in stock options when AOL acquired Netscape because he wanted to be free to start up his own company.

http://www.nytimes.com/1999/07/11/magazine/instant-company.html?pagewanted=2

In 1999 he became one of the co-founders of Epinions.com, a shopping and consumer review website.

Guha left Epinions after a year, and, for a second time, he missed out on making himself a very rich man. By April 2003, Epinions was in trouble and was sold to DealTime, another online shopping site. The result of the deal was Shopping.com. Unfortunately for Guha, he wasn’t around to share in the bonanza 18 months later when, on the day of its IPO, the board members of Shopping.com made an estimated $250 million profit on their shares.

From 2002 to 2005 Guha work for IBM Research and since 2005 he’s been working as Principal Scientist at Google.

      
Tim Bray

worked as Director of Web Technologies at Sun Microsystems until February 2010. He now works as a Developer Advocate at Google.

      
Dan Libby

left Netscape in 1999 to join Ramanathan Guha’s web startup Epinions.com.

In 2001, Libby began working as a private consultant and then moved to Costa Rica where he works on open source projects.

http://osc.co.cr/aboutus/aboutus.html?menubar=aboutus

       
Adam Curry

continues being one of the internet’s most prolific podcasters. He continued producing the Daily Source Code pretty much every day of the week until 2008, when episodes started to become less frequent and the last show, to date, appeared in February 2009. Since October 2007 Curry has appeared on the No Agenda podcast twice a week with John C Dvorak.

In October 2004, Curry co-founded PodShow.

In 2008 PodShow became Mevio – the name change indicating a change of emphasis: away from podcasting and towards slicker, more professional media, in particular video rather than audio. No surprise here since video had originally been what Curry wanted enclosures for in RSS.

       
Dave Winer

sold weblogs.com to VeriSign in October 2005 for $2.3 million (http://news.cnet.com/VeriSign-snags-Weblogs.com/2100-1030_3-5890829.html).

Winer continues to blog almost every day on his Scripting News blog.

So finally, let’s end with some words from Dave Winer, from a Morning Coffee Notes podcast from July 14, 2004.

SOUND CLIP: Dave Winer blog 14 July 2004 – last part of
http://cyber.law.harvard.edu/blogs/gems/crimson1/coffeeNotesJuly14.mp3
from answer 4 to end of podcast

References

Afzali, Cyrus. March 15, 1999. Netscape Launches Publishing Program. http://www.internetnews.com/bus-news/article.php/3_80051

Akin, Lynn. October 1998. Information Fatigue Syndrome: Malady or Marketing? http://www.txla.org/pubs/tlj74_4/akin.html

Andreessen, Marc. January 8, 1999. Innovators Of The Net: Ramanathan V. Guha And RDF, Netscape TechVision. http://web.archive.org/web/20080205163659/http://wp.netscape.com/columns/techvision/innovators_rg.html

Arrington, Michael. July 8, 2005. Profile – Weblogs.com (Ping Server). TechCrunch. http://techcrunch.com/2005/07/08/profile-weblogscom-ping-server/

Beckett, Dave. September 23, 2005. Resource Description Framework (RDF) Resource Guide. http://planetrdf.com/guide/

Bray, Tim. May 21, 2003. The RDF.net Challenge. http://www.tbray.org/ongoing/When/200x/2003/05/21/RDFNet

Bray, Tim. June 23, 2003. I Like Pie. http://www.tbray.org/ongoing/When/200x/2003/06/23/SamsPie

Bray, Tim. March 7, 2006. Atom As A Case Study. IT Conversations recording of a presentation at the O'Reilly Media Emerging Technology Conference. http://itc.conversationsnetwork.org/shows/detail1155.html#

Brickley, Dan. November 7, 2000. RSS-Classic, RSS 1.0 and a historical debt. http://tech.groups.yahoo.com/group/rss-dev/message/1136

Buckner, David. December 12, 2008. Dave Winer: Techno Prophet. http://blog.lib.umn.edu/buckn018/communication/

Burns, Enid. October 11, 2005. More Use RSS Than Have Heard Of It. ClickZ. http://www.clickz.com/3555441

Cluts, Nancy Winnick and Edwards, Michael. October 1997. A Preview of Active Channel and the Active Desktop for Internet Explorer 4.0. http://www.microsoft.com/msj/1097/activedesktop.aspx

CNET News Staff Writer. September 19, 1996. Can Apple make surfing obsolete? http://news.cnet.com/Can-Apple-make-surfing-obsolete/2100-1001_3-230047.html

Cohen, Steven. June 2, 2002. RSS For Non-Techie Librarians. http://www.llrx.com/features/rssforlibrarians.htm

Cover, Robin. April 28, 2007. RDF Rich Site Summary (RSS). http://xml.coverpages.org/rss.html

Curry, Adam. 2004. Adam Curry: payload - Adam Curry's RSS enclosure test channel. http://cyber.law.harvard.edu/rss/examples/rssEnclosuresExample.xml

Curry, Adam. December 15, 2004. iPodder - A brief History, iPodder.org, http://web.archive.org/web/20050720004032/ipodder.org/history

Deatherage, Matt. November 25, 1996. HotSauce and Meta-Content Format. http://db.tidbits.com/article/813

Dornfest, Rael. August 14, 2000. RSS 1.0 Specification Proposal. http://tech.groups.yahoo.com/group/syndication/message/372

ECHET96. February 1997. Navigating the CD-ROM and Conference. http://www.ch.ic.ac.uk/ectoc/echet96/echet96_nav.html

Ellerman, Castedo. March 10, 1997. Channel Definition Format (CDF): Submission to the W3C. Microsoft. http://www.w3.org/TR/NOTE-CDFsubmit.html

Festa, Paul. February 12, 2004. Google spurns RSS for rising blog format. ZDNet News. http://news.zdnet.com/2100-3513_22-134307.html

Geoghegan, Michael. August 7, 2006. Behind the Mic: Doug Kaye. IT Conversations. http://news.conversationsnetwork.org/shows/detail1192.html#

Google Research. 2010. Ramanathan V. Guha: Publications. http://research.google.com/pubs/author17184.html

Grumet, Andrew. April 26, 2005. A slice of podcasting history. Andrew Grumet’s Weblog. http://blog.grumet.net/2005/04/26/a-slice-of-podcasting-history

Guha, Ramanathan. 1996. Meta Content Framework : A Whitepaper. http://www.guha.com/mcf/wp.html

Guha, Ramanathan. 1996. White paper describing MCF 0.95. http://www.guha.com/mcf/mcf_spec.html

Hammersley, Ben. February 12, 2004. Audible revolution, The Guardian. http://www.guardian.co.uk/media/2004/feb/12/broadcasting.digitalmedia

Hardmeier, Sandi . December 18, 2008. Welcome to IE-Vista: RSS. ie-vista.com. http://www.ie-vista.com/rss.html

Jardin, Xeni. May. 14, 2005. Audience With the Podfather. Wired News. http://web.archive.org/web/20050516235657/www.wired.com/news/culture/0,1284,67525,00.html

Kawamoto, Dawn. October 7, 2005. VeriSign snags Weblogs.com. http://news.cnet.com/VeriSign-snags-Weblogs.com/2100-1030_3-5890829.html

Kaye, Doug. October 17, 2004. Behind the Mic: Adam Curry. IT Conversations. http://cdn.itconversations.com/Adam%20Curry%20-%20Behind%20the%20Mic.mp3

Knight, Jon. [Page marked as last updated/links checked on January 23, 1997].Will Dublin form the Apple Core?, from http://www.ariadne.ac.uk/issue7/mcf/

Libby, Dan. August 25, 2000. RSS: Introducing Myself. http://tech.groups.yahoo.com/group/syndication/message/586

Liberatore, Karen. 1997. HotSauce Heats Up: Apple's "Meta Content Format" Is Catching On. http://downlode.org/Etext/MCF/macworld_online.html

Lydon, Christopher. October 3, 2003. Connecting the Dots with Adam Curry. http://blogs.law.harvard.edu/lydondev/2003/10/03/connecting-the-dots-with-adam-curry/

Mappa Mundi Magazine. January 2001. Map of the Month: HotSauce Interface. http://mundi.net/maps/maps_018/hotsauce.html

Maritz, Paul. January 9, 1997. Email to Brad Chase, Ben Waldman and Brad Silverberg. http://www.justice.gov/atr/cases/exhibits/722.pdf

McAlister, Matt. [No date]. Cooking with HotSauce: How to Make a 3D Website. http://downlode.org/Etext/MCF/macworld_online_cooking.html

Netscape. 1999. Instructions for creating a My Netscape channel. http://www.purplepages.ie/RSS/netscape/rss0.90.html

New York Times. July 20, 2004. NYTimes.com Expands Its RSS Feeds to 27 Categories, Adds Most E-Mailed Articles and Multimedia. http://phx.corporate-ir.net/phoenix.zhtml?c=105317&p=irol-newsArticle&ID=593901

Pilgrim, Mark. April 1, 2004. Netscape Returns, Steals Back RSS, Merges With Rival CDF. http://diveintomark.org/archives/2004/04/01/netscape-returns)

PlainText. April 2007. RSS in Plain English. YouTube. http://www.youtube.com/watch?v=0klgLsSxGsU&feature=player_embedded

PR Newswire. June 1, 1998. Netscape Announces 'My Netscape,' a Free New Netcenter Service That Enables Internet Users to Create Personalized Start Pages. http://www2.prnewswire.com/cgi-bin/stories.pl?ACCT=104&STORY=/www/story/06-01-1998/0000670135&EDATE=

Prokpow, Przemyslaw. November 26, 2008. The Evolution of RSS. http://www.articlesbase.com/rss-articles/the-evolution-of-rss-659388.html

Rojas, Peter. May 23, 2005. iTunes 4.9 adding support for podcasts. Engadget. http://www.engadget.com/2005/05/23/itunes-4-9-adding-support-for-podcasts/

RSS Advisory Board. March 30, 2009. RSS 2.0 Specification. http://www.rssboard.org/rss-specification#roadmap

Ruby, Sam. September 2, 2002. Really Simple Syndication. Intertwingly. http://radio-weblogs.com/0101679/stories/2002/09/02/reallySimpleSyndication.html

Snell, James. August 2, 2005. An overview of the Atom 1.0 Syndication Format. IBM. http://www.ibm.com/developerworks/xml/library/x-atom10.html

Twist, Jo. March 25, 2005. 'Podcasters' look to net money. BBC News. http://news.bbc.co.uk/1/hi/technology/4371555.stm

Twist, Jo. April 11, 2005. Turning the web into 'sushi belts' from BBC News Web site. http://news.bbc.co.uk/1/hi/technology/4421707.stm

Waddington, P. 1996. Dying For Information? A Report On The Effects Of Information Overload In The UK And Worldwide. http://www.ukoln.ac.uk/services/papers/bl/blri078/content/repor~13.htm

Wikipedia. As of March 2010. Dave Winer. http://en.wikipedia.org/wiki/Dave_Winer

Winer, Dave. January 20, 1997. Example of MCF file describing Dave Winer’s scripting.com site. http://www.scripting.com/frontier/siteMap.mcf

Winer, Dave. March 29, 1997. About Fat Web Pages. http://www.scripting.com/fatPages/about.html

Winer, Dave. August 7, 1998. scriptingNewsToXML. http://www.scripting.com/fatPages/websites/scriptingNewsToXML.html

Winer, Dave. May 8, 1999. Update on My.UserLand.Com. http://static.userland.com/userLandDiscussArchive/msg005830.html

Winer, Dave. June 15, 1999. ScriptingNews 2.0b1. http://my.userland.com/stories/storyReader$11

Winer, Dave. September 1999. A Bright Future for Syndication. http://davenet.scripting.com/1999/09/03/theDarkSideOfSyndication

Winer, Dave. June 7, 2000. RSS 0.91. http://www.scripting.com/2000/06/07.html#rss

Winer, Dave. October 31, 2000. Virtual Bandwidth. http://www.scripting.com/Davenet/2000/10/31/virtualBandwidth.html

Winer, Dave. January 11, 2001. Payloads for RSS. thetwowayweb.com. http://web.archive.org/web/20010202144800/www.thetwowayweb.com/payloadsForRss

Winer, Dave. November 15, 2002. RDF was a bully. http://lists.xml.org/archives/xml-dev/200211/msg00647.html

Winer, Dave. 2003. An example of the <scriptingNews> XML format. http://essaysfromexodus.scripting.com/xml/scriptingnews2.xml

Winer, Dave. July 15, 2003. RSS 2.0 Specification. http://cyber.law.harvard.edu/rss/rss.html

Winer, Dave. July 18, 2003. How to support enclosures in aggregators. http://cyber.law.harvard.edu/rss/enclosuresAggregators.html

Winer, Dave. August 24, 2003. RSS 0.92. http://backend.userland.com/rss092

Winer, Dave. September 9, 2003. All the Lydon interviews in one download. http://blogs.law.harvard.edu/lydondev/all-the-lydon-interviews-in-one-download/

Winer, Dave. July 14, 2004. Morning Coffee Notes podcast . http://cyber.law.harvard.edu/blogs/gems/crimson1/coffeeNotesJuly14.mp3

Winer, Dave. February 21, 2007. Dave Winer bio. http://www.scripting.com/stories/2007/02/21/daveWinerBio.html

The name of this technology? It used to be called Interix, then became Services for UNIX (SFU) as they added more bits on top of Interix, and is now known as Subsystem for UNIX-based Applications (SUA). The current name is more of a mouthful, but is a more accurate name.

Microsoft don't advertise SUA. Some of us have been using it, and its predecessors, for years. But, on the whole, it's a pretty well kept little secret. And, not surprisingly, it's only available on the server versions of Windows, or the desktop versions aimed at business users and IT professionals.

So, to run SUA, you need one of the following versions of Windows:

• Windows Server 2008
• Windows Server 2003 R2
• Windows 7 - Enterprise or Ultimate Edition
• Windows Vista - Enterprise or Ultimate Edition
        

To enable and install SUA:

1. Go to the Control Panel.
2. Click Programs and Features.
3. Click Turn Windows features on or off in the left panel.
4. Select the check box for Subsystem for UNIX-based Applications.
   
   
5. Click OK.
6. In the start menu, click All Programs > Subsystem for UNIX-based Applications > Download Utilities for Subsystem for UNIX-based Applications.
   
   
7. Download the SUA installer from the Microsoft website.
8. Once downloaded, double-click Utilities and SDK for UNIX-based Applications_X86.exe in your downloads folder.
9. Step through the auto-installer.
   
   I'd recommend you choose the custom setup and enable the GNU Utilities and then, in the following step, select all three check boxes to allow su to root, enable setuid and enable case sensitivity.

      
Now, you can go back to the Subsystem for UNIX-based Applications start menu item and launch a Korn shell or a C shell and, within that shell, run UNIX commands:

I know a lot of developers who don't like SUA, but personally I've always liked it. It's really handy sometimes to have UNIX commands available within Windows, and it's a great way to familiarise yourself with UNIX tools like vi.

An important resource for SUA users is the SUA Tool Warehouse:
http://www.suacommunity.com/tool_warehouse.htm

The latest edition to my recording is a smart new microphone on an anglepoise arm:

It's a Rode Procaster and the main difference between it and other microphones I've used is that it's a dynamic microphone. Previously I've used condenser mics that need phantom power, but I've always had problems with hiss. The Procaster gives a great sound and wasn't break-the-bank expensive. I think it's very good value for money.

You can hear it in use on ITauthor Podcast #33.

      
The other bits of kit are things I've put together over a number of years:

M-Audio FastTrack Pro

This is really just a very nice external sound card. I need one of these because the sound card on my Dell Vostro is really, really, really awful. Even just for listening to audio normally it's bad: terrible hiss and interference from the spinning of the hard disk.

I have two of these so that I can route Windows sounds into Skype, so that the person on the other end can hear sound files I play.* This is a luxury: you don't need this. And if you're lucky enough to have a good sound card you don't need either of these (but I love these things anyway - you great great sound out of them).

*I just copied Joel Spolsky's Skype setup podcasting setup: http://www.joelonsoftware.com/articles/PodcastEquipment.html
       

I bought this years ago and it's probably the bit I'd replace because it's not digital, so I lose a bit of sound quality by sending an analogue signal through this. But it's useful to have physical knobs to turn to get the levels right, and it allows me to do the Joel Spolsky method of Skype recording.
        

This is something else I've had for a few years now. It's a very simple little recorder but it does the job and is handy for recording away from home because it's small and very lightweight.
       

I wasted money on this. This is a great set of headphones: very comfortable to wear and a nice, warm, bassy sound, but I never managed to get good sound out of the microphone. As I mentioned above, this is a condenser mic and, through my setup, it always gave me hiss. It also has a thin, tinny, metalic sound that was really disappointing because this was an expensive headset.

TweetDeck is a phenomenal piece of work to be created by one man. Hats off to the guy!

But why does someone go to the trouble (and it must have taken a serious amount of work) to create application as superbly usable as TweetDeck? To make some money out of it? How do you make money out of something that's given away free? Iain Dodsworth explains his plan:

The early years where he hooked up with a brilliant young engineer called Steve Wozniak and got him to design circuit boards that people still consider works of engineering artistry. The huge success of the Apple II in the late '70s when the microcomputer industry was in its infancy. His immediate grasp, on visiting Xerox PARC, of the business potential of the mouse and graphical user interface. The Apple Lisa and then the phenomenon that was the Macintosh. His sacking from Apple in 1985 and the launch of NeXT (identifying UNIX as the operating system that would allow him to continue pursuing the ideas he'd been trying to develop at Apple). The $10M purchase of a division of Lucasfilm the following year (which went on to become Pixar). The transformation of that $10M into a $585M share value when Pixar went public in 1995. The stagnation of Apple without Jobs. His return to Apple in 1996 (shortly afterwards taking on the mantle of "interim" CEO - as if anyone was fooled that he wouldn't stick around). The uber-stylish iMac in 1998 (the first of the iBrands and the fast-selling Macintosh ever). The license to print money that was the iPod/iTunes application/iTunes Music Store triumvirate. The successful replacement of the old Mac OS with Mac OS X, an operating system based on the work done at NeXT. And then in 2007 the launch of a mobile phone - but not just any mobile phone - of course it's not - this is Apple, so it just has to be, indisputably, the best mobile phone ever.

So that's all well and good. But out of all his background of success and his personal qualities - his obsession for beautiful hardware design, his extreme attention to detail, his ferocious determination to protect Apple's intellectual property, his own personal self-branding, his Wonka-esque control over what information comes out of Apple - out of all this, what is it that makes people follow Jobs, and hang on his every word, like no other business leader.

For an answer, look no further than this footage from Apple's sales conference in Hawaii in October 1983:

It's his passion, his complete commitment and his palpable belief in the importance of what he's saying that make this so totally captivating. If Jobs had been an army recruiting sergeant, looking for recruits to fight the evil Big Blue, I'd have enlisted on the spot. 

OK, to be honest, that's me. That's usually what I'm saying - or at least thinking - when it's time to ship the product to customers. And I've always told myself the reason I'm like that is because I'm a perfectionist and the reason I find it difficult to wrap something up - and say "It's good enough. Customers will get more value from getting this documentation now than from waiting a couple of weeks and getting it late" - is because I have such high standards. Turns out I'm probably kidding myself.

The lizard brain

In this video Seth Godin (author of Linchpin: Are You Indispensable?) explains why the resistance to shipping (and by shipping I mean getting stuff finished and despatched/published/released) is just another symptom of our lizard brain at work.

Seth Godin: Quieting the Lizard Brain on Vimeo

Thrash early

Another concept Seth Godin raises in his presentation is one of Steve McConnell's: thrash early. "Thrash at the beginning because thrashing at the beginning is cheap." In this context, "thrashing" means working without making any progress. The expression was coined, I believe, by Frederick Brooks, in The Mythical Man-Month where he described great beasts, long since extinct, that had strayed into a tar pit, thrashing about with all their might but not making any progress to escape their predicament.

In the following diagram McConnell illustrates the situation where a lack of process and planning at the start of a project results in an increase in thrashing, and a decrease in coding progress, the longer you spend on a project.

Diagram from Steve McConnell, Professional Software Development.

When a project has paid too little early attention to the processes it will use, by the end of a project developers feel they are spending all of their time in meetings and correcting defects and little or no time extending the software. They know the project is thrashing. When developers see they are not meeting their deadlines, their survival impulses kick in and they retreat to "solo development mode"—focusing exclusively on their personal deadlines. They withdraw from interactions with managers, customers, testers, technical writers, and the rest of the development team. Project coordination unravels.

Steve McConnell, "The Power of Process", IEEE Computer, May 1998

Among the things Scott and Chris discuss are:

• Being an advocate for the people you manage
• Getting things done means ignoring emails ("At Microsoft you either write code or you delete email")
• "No meeting Wednesday"
• Weekly or daily task setting and progress reporting
• Prime motivators for getting things done: shame and fear

Chris talks about Scott reduced posting to Computer Zen since becoming a manager. I think what he's saying is: you can be a good manager, a good website contributor, a good husband, a good father - but you only get to choose one of the above.

I'd like to think that's not true.

Please note: This video is from Microsoft's Channel 9 website and (I'm guessing) is the copyright property of Microsoft, or maybe of Scott Hanselman. Go to the original page on Channel 9 to see the video in its Channel 9 context, complete with comments.

Other links:

• Channel 9's RSS feed: http://channel9.msdn.com/Feeds/RSS/
• Hanselminutes on 9 Web page: http://channel9.msdn.com/tags/HanselminutesOn9/
• Hanselminutes on 9 iPod feed: http://channel9.msdn.com/tags/HanselminutesOn9/feed/ipod/
• This particular video: http://channel9.msdn.com/posts/Glucose/Hanselminutes-on-9-Follow-up-6-months-later-with-Chris-Sells-on-Managing-People-and-Your-Time
• Scott's audio podcast: http://www.hanselminutes.com/

I've got a MadCap Flare project that I want to publish as open source code for anyone to go and download. It turns out this is extremely easy to do using Google Code. And Google Code has the benefit of allowing you to sync your work with the online source files using SVN (Subversion).

Multiple people can work on the project simultaneously and each time you open the Flare project the SVN plugin for Flare asks you if you want to use the most up-to-date files from the online repository. When you've finished making changes you just commit your changes, straight into Google Code, without having to leave Flare.

Here's how to create a project in Google Code and add a Flare project.

Prerequisites:

• For the initial upload of files into a Google Code project I'm using TortoiseSVN. You can download this from http://tortoisesvn.net/downloads. TortoiseSVN allows you to work with a Subversion repository from the right-click menu of Windows Explorer.
• You will sign into Google Code using a Google account, so you need one of these if you haven't got one already. If you use Gmail you've already got a Google account, so use that.
• You are going to commit files into a publicly viewable repository. Even if you delete a file from the repository, people will still be able to browse previous revisions of the project and view the file. Versioning repository systems like Subversion are designed to keep a historical record of everything that happened to the repository, so there's no easy way to remove all trace of a file that you didn't mean to upload.* So, before adding a project, make sure that you remove any files that you don't want other people to see.

To put a Flare project into Google Code:

1. Go to http://code.google.com/p/support/wiki/GettingStarted and read through the information about project hosting.

2. When you're ready, go to http://code.google.com/hosting/createProject, fill out the simple form and click Create.

   You will now have a Google Code project with one project member: you (or, to be more precise, your Google account).

   You are the project owner. To allow other people to commit changes to the project, you can add more project members from the Administer tab.

3. Click the Profile link (top right of the page).
4. Go to the Settings tab and copy your googlecode.com password.
5. Now go to Windows Explorer and browse to the directory that contains the Flare project you want to add.
6. Within the project directory select and cut the Analyzer and Output directories.

7. Paste the Analyzer and Output directories somewhere outside of the project directories.

   This is to avoid these directories being added to the repository.

8. Do the same to the Project/Reports and Project/Users directories, moving them out of the project for now.

9. Right-click your Flare project directory and choose TortoiseSVN > Import.
   

10. In the Import dialog box, enter the following as the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk
    

11. When prompted, enter your user name and password.

    These are the user name of your Google Code account (e.g. the bit before the @ symbol in your Gmail address) and the googlecode.com password you copied to the clipboard.

12. Click OK.

    This will now add all of the files/directories to the SVN trunk in Google Code.

    TortoiseSVN displays the progress.
    
    If you have a lot of files in the project this may take some time.

13. When the import finishes, click OK to close the dialog box.
14. Move the Analyzer, Output, Project/Reports and Project/Users directories back within the Flare project directory again.
15. Still in Windows Explorer, in the directory that contains your Flare project directory, right-click anywhere on the background to the main pane of Windows Explorer and choose SVN Checkout.

16. In the Checkout dialog box, enter the URL of the repository:

    https://<PROJECT-NAME>.googlecode.com/svn/trunk

    and the Windows path to the Flare project directory (that is, the directory you just imported into Google Code) as the checkout directory.
    

17. Click OK.

    The files you imported are checked out and marked as under version control.

    A little check mark on the file icon indicates that TortoiseSVN knows they are part of a Subversion repository.
     

18. In your browser, go to the Source tab of your Google Code project.

    For example, http://code.google.com/p/itauthorflare/source/browse/

19. Click trunk and you should see all of the files you uploaded.

    

You can now start Flare and open your project and (if you have the SVN plugin) you will be asked if you want to load the latest version of the files from the SVN repository.

* Note: If you forget about clearing out sensitive files and you discover you've uploaded something you really don't want anyone to see, then you can remove all the revisions within the project - in other words you can empty the project and return it back to its initial state before you imported any files. You do this by resetting the repository.

To do this, go to the Source tab in your Google Code project and click the reset this repository link near the bottom of the page. Be aware that this removes everything from the repository, so you should never do this for a project that has an active community working on it, or a project with any sort of a history because this history will be destroyed by resetting the repository. But if you've just started and then realised there's stuff in there that shouldn't be, then it's a way out of a fix.

Rahul Prabhakar writes:

Koreans place a lot of emphasis on title; it could be said that nowhere in East Asia does title hold more prominence than in Korea. Try addressing a Korean colleague of the same age group but higher designation with his name, and chances are you'll be asked to prefix a title. If you don't use a title to address someone higher in the value chain, Koreans are likely to consider you disrespectful or discourteous.
If the distance between top- and bottom-level organizational hierarchies is wide, technical communicators should resort to formal communication. If the culture encourages a flat organization, the communication automatically becomes less formal. In order to succeed in a Korean company, you must consider the hierarchy between you and the final decision maker. Allow everybody in the middle to give their opinion and be included as much as possible.
...
Korean companies don't understand why technical communication is important. For them, it's always an afterthought or an additional burden.

Without seeing/hearing the screencasts it's not easy to form an opinion, so I thought I'd let you have a look. Let me know what you think. Are you put off by the ums and ahs, and the little mistakes I correct as I go along, or does it lend authenticity to the demo? Personally, I wouldn't mind seeing a demo like this as part of the user assistance for a product. I think the effects that Camtasia lets you add (zooming in and the rotating cube effect) lend a little polish to make up for the ad hoc presentation style. But it's probably not everybody's cup of tea. What do you think?
 

 
Please note:  When I recorded this it was purely meant for internal use within my company. However, I've had a look at it and I'm confident it doesn't give away any corporate IP. It does, however, reveal (if you look closely) that I had to Google to find a solution to a buzzing microphone shortly before starting the recording!  :-)

Alternative larger format video  (you'll need to wait a little while for it to download, but the picture quality is better).

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.

Very few people these days will sit down and read a manual for a new software product. The expectation is that we can install software and start to use it straight away. The younger generation in particular is so comfortable with new technology that they dive in and expect it all to work. They explore fearlessly, and are able to master complex hardware and software concepts effortlessly.

If a user has a problem when they are using the software then they will generally either ask a colleague for help or resort to trying to find the answer in the documentation. Typically, they will “dip into” either a manual or the online help and at this point, if they can’t easily find the exact piece of information they need, they will be frustrated with the software.

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

Rhonda asks “Are humans ‘programmed’ to learn by trial and error and not ‘by the book’?” I think she’s onto something. I suspect that over millions of years of evolution a genetically programmed impulse to play around with things as a way of figuring things out has served the human species extraordinarily well. And so today, if given some software (or hardware), plus a set of instructions telling you how to use it, most of us will ignore the instructions and just try to start using the product.

For example, yesterday, for the first time, I was using the PushOK SVN plugin for Madcap Flare to work on our main online help project. My colleague Graham and I were both working on the same project at the same time. He’s been using the plugin for a while and I was on the phone to him asking him questions and we were working things out, in the style of: “Okay, now I’m going to click on such and such … now see if you can … did that work for you … did you get my changes?” And pretty soon I’d figured out how to do the basic stuff: check out, update, commit. Part of the thing that demanded some trial and error on our part was that the source control menu text within Flare uses Microsoft Visual Source Safe terminology rather than the standard CVS/SVN terminology we’re used to (for example, “check out” means something different).

At one point in proceedings, as we were batting things back and forwards figuring out how it worked, I joked to Graham: “You know what we really should do? We’re technical writers - we really should be looking in the help system!”

Like most people (and I quite often bore people by asking them if/when/how they consult the documentation for the software they use, so I’m pretty sure I’m part of a majority in this respect) I only consult the help system:

• If there’s no local expert around to ask
• If I’m in a situation where I don’t want to ask the local expert because I don’t want to let on I don’t know whatever it is that I don’t know
• If I can’t find the information via Google, or I happen to know the help system will do the business for me (for example, I know I can easily find details of FrameMaker keyboard shortcuts in the application’s online help, but, in contrast, I know there’s little point looking in the online help for Microsoft Word because the search facility brings back so many inappropriate results it’s far quicker just Googling for the information)

And what about printed documentation? (It’s funny, when I talk about “documentation” a lot of people still immediately think of printed books, when in fact the work we produce only rarely ends up being printed. This is probably one of the reasons some folks prefer to talk about “user assistance” – but I find that term confuses most non-IT-professionals.) Well, let’s think … when do I read the paper manual for a software application … emm … never? Since I got broadband access to the internet (back in 2003 I think), I can’t remember ever having consulted a paper manual as a way of finding out how to do something in a software application. And I used to spend a small fortune on computer books. Before my access to the internet was “always on” my home office was cluttered with stacks of computer books and binders full of printouts. In the last few years all of that stuff sat untouched, gathering dust, and it was only towards the end of last year that I finally got round to chucking it out.

But back to Sue Wooley’s article:

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

If you document software applications then you’ve almost certainly had the experience of having to document something when you know you’re writing a whole screed of instructions to compensate for a poor piece of user interface – and it’s obvious that simply moving things around the interface would make this bit of documentation redundant. That’s when documentation can be a bit soul-destroying. You of course petition the developers, log a bug or submit a change request, but in the meantime you have to document what’s there, in the full knowledge that you shouldn’t have to be writing this and the best outcome (for the end user) would result in the deletion of your work.

However, we have to be pragmatic about such things. Sometimes user interface design is just left up to some poor developer who, while he/she may be fantastically clever and a brilliant coder, has no real understanding of usability. And once a bit of poor user interface design slips out into a release it can be very difficult to repair because, unless they’re backed up by complaints from customers, requests for changes to the user interface generally get assigned a low priority. This can be very frustrating, if you’re the one who raised the issue, because some of these things can cause a lot of damage to usability but could be fixed by a little, two-minute change in Visual Studio. The hidden reality, though, is that even a quick two-minute change in Visual Studio can sap QA time by requiring changes to test scripts, updates to automated tests, manual regression testing, and so on. So a two-minute user interface change, that might prevent several hours of work by a technical writer, is often destined never to happen because of the QA cost and the feeling that any additional change carries a risk: so if it ain’t really broke, don’t fix it.

I don’t believe documentation should ever be thought of as “a complete solution in itself” (it should be an integral part of a product), but neither is it always “a backup for deficiencies in the user interface”. The products I work on are usually large, complex systems, where there’s simply too much in there to show it all on one page or in one window ­– with everything achievable within two or three clicks. Some of it just has to be tucked away somewhere to allow other things to be more accessible. As a result, you need some way of helping people find the rarely used pieces of functionality. Unfortunately you just can’t always make complex things simple within an application. Some things need explained. And as for training, well, you can develop and deliver a great training course, but what happens when someone completes a four-day course, covering lots of detail, but then doesn’t need to use a particular bit of the application until six months later?

There are good reasons why documentation is necessary. But, having said that, I’d still maintain that, in reality, for most of us, documentation is the form of assistance that you go to as a last resort, when there’s no other option.

But don’t get down-hearted. If you can create a help system that’s well targeted to provide people with the information they’re realistically going to be looking for, if you can structure it in such a way that people can find the information they need quickly without having to trawl through a list of 20 unordered search hits, if you can write concise and easy-to-read topics that explain just that nugget of information the reader needed to know … then your work is not in vain. Somewhere, some time, you’re going to help someone out. You’ll have avoided some aggravation. You’ll have reduced that day’s global curse count.

And sometimes, no matter how great the help system is, people will choose to ask a human being for help. Why? Well, because we’re social creatures and we’re often just looking for excuses for social interaction. Asking for help with the new IT system (or maybe just bitching about it generally for a while: I mean, the old system worked just fine – now I can’t get anything done!) is a chance to interact with someone, get to know the person at the next desk, chat to the girl in the next booth, make friends or maybe just kill some time.

And anyway, what’s so bad about providing a last resort? Isn’t it good to know we’ve provide people with something they can turn to when all else fails?

This is something we’ve probably all come up against at some point in our careers. Fortunately I work for a company where common sense tends to prevail and a well-reasoned argument, from any source, can be influential. But I know of lots of companies where things are very different. Documentation is often seen as just a cost centre. And when the spreadsheet guys are looking at what’s costing money and what’s winning new business it often looks like documentation is something you could do without. Because – think about it – when did good documentation, by itself, ever win one dollar of new business?

The referee was fantastic!

So, how does a documentation manager prove to the numbers guys that they need to spend money on documentation? It’s not easy. And the reason it’s not easy is partly down to the referee scenario. Think of a great football game (and I’m not talking US-type football here, I’m talking about the football the rest of the world plays). With a great game of football you’re never left talking about the referee at the end of the game. In fact after any game of football you never find yourself talking about the referee unless he did a bad job. You rarely notice the referee if he makes good decisions, lets the game flow, nips trouble in the bud, acts impartially … does his job well. You only notice him when he disallows a perfectly good goal, books the wrong person, consistently favours one team, awards a last-minute penalty when it was a blatant dive, and so on.

It’s the same with documentation. People only start talking about the documentation when it’s incorrect, badly written or absent. With documentation: no news is good news. And this is dangerous. It’s easy to cut the documentation effort because initially no one will notice the difference. The quantity and/or quality of output from the docs team will drop off, but because much of the documentation effort is for new product that’s not going to be released for a while – and even once it is released it won’t be the documentation that customers focus on first – and because the docs team will still endeavour to make sure the high priority work still gets done, it’s going to be a while before this change affects customers. In other words you can get away with it for a while before shit starts to hit fan.

The reverse is, of course, true. It takes a while for cuts in documentation resource to work through and start hurting your customers, but it also takes a while to recover from that situation once the powers that be have decided something needs to be done. In fact, after the problem has been recognised things will continue to nose dive, even after you’ve recruited replacement staff, and even supposing the replacement staff don’t need any training and can magically walk in and start being productive from week one. During this time more and more customers will be hit by the documentation-related problems. A head of steam will build up. Customers will talk amongst themselves about how difficult the software is to use. News might even spread to prospective customers. But by this time the damage that was done was done months before – and there’s no quick fix.

It’s back to the referee scenario. Not only do customers never talk about the documentation unless they’ve got something to complain about, but it’s also true to say that while documentation never won a sale, it is sometimes a contributory factor in a lost sale.

This is the point in proceedings – when you’re doing your best to recover from resource-related documentation problems, but customers are still complaining – that necks are on chopping blocks and axes are poised. And you can bet those necks aren’t the necks of the budget police who wouldn’t let you replace a colleague who left, or wouldn’t grow the docs team in line with the growth in the development team, or who “restructured” the docs team to allow budget to be reallocated to more profitable areas of the business.

Docs are important? Go on then … prove it!

This all sounds very grim. So how do you avoid getting into that mess? You might be convinced that what you do is important – but how do you convince others? How do you prove the value of what you’re paid to produce? How do you answer the question Ivan Walsh got asked: “What metrics do you use to tell if the documents are successful?”

Well I’ve been thinking about this and reading around and there’s surprisingly little out there to help me answer this question. There’s been quite a bit written about what metrics you might use to judge individual technical writers – and maybe measure one technical writer against another – or how you can assess the quality of particular documentation deliverables – for example, the number of comments that were raised during pre-publication review, or the number of documentation bugs raised after publication. But the metrics we’re talking about here are measurements of the value of the documentation effort within your company.

I came across a LinkedIn discussion that mainly concerns the micro-metrics of assessing particular documents or writers (rather than the macro-metrics of assessing the documentation effort itself) but these two quotes, I think, touch upon the bigger picture:

in the final analysis any document is only valuable if it answers the questions the user has so they are not required to make some sort of call to a support person

Keith Oxenrider

A better measure is the readers' view of the documentation. Do they like it? Can they use it to solve their problems? Does the documentation reduce the number of calls to the tech support center? Does the documentation aid the tech support center in quickly resolving client problems?

Dave Gardner

The references to support point to a possible solution.

Donald S Le Vie Jr wrote an interesting and useful article in the December 2000 edition of Intercom (“Documentation Metrics: What Do You Really Want to Measure?”), although he mainly discusses writer-specific metrics that he believes you really shouldn’t bother trying to use – for example, hours per page, pages per hour, documents released per month or per writer, errors per page, percentage of time schedule dates were met, etc. However, he ends the article with some metrics he believes are useful:

• Web-based feedback – e.g. find out what customers want more of, or don’t need, in future versions of documentation
• Customer usability of beta or final versions of documentation. Get them to rate the documentation.
• Team up with Customer Support to make sure it’s recorded when support calls are documentation related.  “Track this information over time to show the decrease in the number of documentation-related calls so you can assign a dollar figure (a quantitative measure) to any metric.”

Le Vie stresses the importance of regularly broadcasting these metrics throughout management.

Conclusion

In the LinkedIn discussion Padric O'Rouark says:

Sell “help” separate and you would find very few buyers.

That’s true, but it’s also misleading. The fact that you wouldn’t pay for something does not mean it has no value. When I buy a bed from Ikea I expect to find instructions on how to assemble it when I get it home. I wouldn’t pay for those instructions separately though. If I was expected to do this I’d just shop elsewhere. As an aside, the poor quality of Ikea’s assembly instructions is one of the things that makes me dislike the company as a whole (that and the fact they try and steer you round the whole store before you get to the checkout, rather than letting you get in, get what you want and get out).

If customer satisfaction is important to a company then the philosophy of doing only as much as you need to do to make a sale, and not one jot more, probably only works if you’re a make-a-quick-buck-and-disappear business, or if you’re competing solely on price and you’re confident customers will accept poor quality products and bad customer service just as long as the price is right.

Customer-facing documentation has no place in a cut-price or fly-by-night business. But in the software business where companies need time to grow and therefore customer retention is important, user assistance is valuable. If you’re trying to sell corporate software then the people with the purchasing power, the decision makers, aren’t the people who are going to be using the software day in, day out. But if you’re in the business for a few years then some of those people who have to use the software in their daily jobs get promoted and end up being decision makers, or at least decision influencers. If you’ve had to struggle for several years using a badly designed bit of software from Company X, that had little or poorly written user assistance, then, later in life, when you get the chance, you’re going to make damned sure you don’t let  Company X inflict any more such pain on any of your staff!

It’s hard to come up with metrics to justify the current size of the docs team, beyond all argument. Bean counters are interested in having more beans to count, so winning new deals and satisfying contracts in order to be paid quickly are things that tend to impress them. In this regard, you could look at the number of documentation requirements within Request For Proposal documents from prospective customers, or you could find out whether documentation was scored as part of customer acceptance tests? 

But other than that, what can you come up with to use as proof of your value to the company that pays your wages? Well, the source of your wages may be the key, because really it’s your customers who pay your wages and they are the only ones who can provide metrics that will convince management of the value of what you’re doing.

I started this piece by suggesting that if you sack tech writers, or reduce the proportion of writers to developers, sooner or later customers will start to suffer. If that’s true then it should be measurable. Keep a record of the number of documentation-related support calls or bad customer feedback mentioned in engineer site visit reports. Have numbers gone up or down over the past six months?

You might never be able to prove that customers are happier because of the work you do, but if you’re able to prove that customers are less annoyed with the products and increasingly able to get on with their business without calling support, then you might just be able to convince people that documentation is valuable.

In this example, all the new button does is change the h1 heading style, giving it an orange background, but you could have buttons to completely change the whole look and feel of your WebHelp – to give readers some variety – or you could add a button that darkens the window and display a lightbox-style popup containing a video of you juggling cats. You might have more useful applications for this functionality, but you get the picture: the functionality is there for you to use however you want. The trick is how you add a button and then how you make that button call a JavaScript function. After that the rest is down to your own JavaScript/jQuery skills. 

So, the following assumes that each topic page in your WebHelp calls a JavaScript file where you keep all the cool, dynamic stuff you want to do when a reader clicks around in your help files. For example, I have a JavaScript file called MyWebHelp.js that uses a lot of jQuery to do stuff, so the head element of each HTML page in my help projects contains the following:

<script type="text/javascript" src="Resources/JavaScript/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="Resources/JavaScript/MyWebHelp.js"></script>
        

To add a function button to the WebHelp toolbar
    

1. Create an image to serve as the toolbar button and save it as a .gif file.
   
   If you want the button to change on hover, or when clicked, then you can create 2 additional images for these states.
   
   These are the 3 images I used in this example:
   
        
2. In your JavaScript file add a function that you want to call when the toolbar button is clicked. For example, this function (using jQuery) adds an orange background to the h1 heading on the page (pretty useless, I know, but it illustrates the point):
   
   function makeHeadingOrange() { 
       $('h1').css('background-color','orange');
   }
3. From the Project Organizer in Flare, open the skin you want to modify.
4. Click the Styles tab.
5. Select Toolbar Item.
6. Right-click Toolbar Item and choose Add Class.
7. In the New Style dialog box, enter a name for your button class (for example, makeHeadingOrange).
   
   
8. Click OK.
9. Expand the Toolbar Item list and select your new class.
10. In the Basic properties for the class, click in the value column for Icon (this will currently be displaying “not set” as its value).
11. Click [Browse for image…] and find the button image you created.
    
    Notes:
    - When you specify an image it becomes part of the binary project data. The image file itself is not saved as a resource, like your screenshots, so you can only choose one of the existing images that have been absorbed into the project file, or incorporate a new image by browsing for it.
    - The images in this list are not sorted into alphabetical order. New images are simply added to the bottom of the list.
    
    
12. Choose images for the PressedIcon and HoverIcon properties (you can use the same image for all three states if you want).
13. Add a tooltip – for example, Make main heading orange.
14. In the Type properties for this class set ControlType to Button.
15. Set Onclick to the name of the function you want to call – in my example it’s makeHeadingOrange().
    
    
16. Click the WebHelp Toolbar tab.
    
    Your new button class is now shown in the Available list.
17. Move the button class into the Selected list and position as required using the up/down arrows.
    
    
18. In the section “Custom Javascript to include in Toolbar page”, click Edit.
19. Paste the following into the Toolbar JavaScript dialog box:
    
    function makeHeadingOrange() {
          parent.frames['body'].makeHeadingOrange();
    } 
    
    
    
    This creates a function called makeHeadingOrange which, when called, in turn calls another function called makeHeadingOrange. This second function is the one you added to your main JavaScript file in step 2 of this process. You could call them by different names if you wanted – but I think it’s clearer to call them the same thing. This second function is in a JavaScript file that’s referenced in your topic files and it isn’t directly accessible from the toolbar frame, so the first function (the one you added in Flare) is used to call it from within the context of the frame named “body”. The “body” frame in Flare WebHelp is the main frame within which the help topics are displayed. You could locate the code for the second JavaScript function within the topic HTML itself, but it’s going to be far easier if this function resides in a JavaScript file that you reference in the head of your topic pages.
    
    You can include as many custom Javascript functions as you want, listed one after the other in this dialog box. When the project is compiled, the text in this box becomes a file called Toolbar.js in the Data/<skin name>/ directory of your WebHelp output.
    
    So, if you want to, you can have lots of buttons, each calling a different function in your main JavaScript file (via the functions in the Toolbar.js file).
20. Click OK to close the Toolbar JavaScript dialog box.
21. Save your changes.
22. Build the WebHelp target output and test the results.
    
    Hovering over the button:
     
    
    Clicking the button:
     

Searching for a solution, I found an explanation of what was happening, plus a very nice little free fixer tool here:

http://forums.cnet.com/5208-7594_102-0.html?threadID=308647

All Panasonic,JVC and Canon mpeg2 camcorders that generate MOD files on either HDD or SD-card do not set the widescreen flag in the mpeg2 sequence headers in 16:9 mode. Instead they leave it as 4:3 and put the information, whether 16:9 or 4:3 was used, inside the corresponding MOI file.
        Unfortunately most video player or editing software do not evaluate the content of the MOI file and therefore the video remains in 4:3.
        I have written a small tool sdcopy that can automatically correct the 16:9 flag of multiple MOD files. In addition, it can automatically copy all found MOD files(of all subfolders) into a single target folder. Sdcopy does not modify or decrease the video quality, it just patches the headers.
        You can download sdcopy from here, its freeware:
        http://zyvid.com/smf/index.php?action=dlattach;topic=280.0;id=218

 
I’ve used SDcopy and it did exactly what I wanted: produced videos that opened up in Media Player in 16:9 and, in the process, gave the files much more meaningful file names.

Your problem may be that the Flare database for your project has got messed up in some way. The symptoms of this are that you can be typing in the editor but no characters are showing up, then, after you wait a few seconds they appear, so you go on typing, but then things slow up again.

Flare uses a Microsoft SQL Server database to keep track of the interconnections between topics. This helps prevent you screwing things up when you delete a topic – because Flare will ask you what you want to do about all the references to that topic and will convert all the hyperlinks to normal text, if that’s what you want to do.

To repair a messed up database:

1. Save your work.
2. Close the project and Flare.
3. In Windows Explorer, go to the Analyzer subdirectory for the project.
   
   
4. Delete the files in this directory.
5. Restart Flare and load the project.
   
   Flare will rebuild the database. This will take a few minutes, depending on the size of the project – during which time you’ll see lots of activity in Flare’s status bar – but once it’s done you should have a nice speedy Flare again.

The other things you can do to speed up Flare a little are:

• Disable phrase collecting (choose Tools > Options > Analyzer and remove the selection from the check box). This turns off the phrase suggestions that you see in the Intellisense popups (if you have that turned on). If you don’t use this, turn it off.
• Turn off Intellisense all together (choose Edit > Intellisense and remove the selection of Enable Intellisense). Personally, I found this feature annoying rather than useful, so I prefer to have it turned off anyway. 

And with formatting and styling it’s pretty much the same story. By using CSS, you have a high degree of control over the look and feel of your output. For example, I’m working on a WebHelp system right now and it’s been fairly straightforward to get most of the output looking more or less how I want it to look. The simple things like changing the background colours, the fonts, the icons, and so on are easily done from within the Flare application. And there are other things you can achieve by using Javascript to inject a CSS file dynamically on page load, if you want to override things in the Flare stylesheets that are injected into your output files at build time.

However, I’m painfully reminded, working with Flare again today, that one of the reasons I’m not 100% of a Flare fan is that Madcap fell short of making the styling of output 100% configurable via stylesheets.

Things like the Related Topics popups rely on Javascript, triggered by an onClick event, to add elements to the topic. This is perfectly standard, but whoever coded this decided in their wisdom to embed style information directly into those HTML elements, rather than giving everything a class name and controlling the styles from a stylesheet. In the hierarchical system that is CSS, nothing gets to overrule styles applied directly within the style attribute of an element in the HTML, so if the coder coded:

color="black"

then you you can have any colour you want, as long as it’s black – that is, you don’t get to modify the colour in your stylesheet to something more subtle, you’re stuck with the coder’s idea of what looks best for your output.

So my particular example today was that I was trying to beautify the Related Topics popup a little. Here’s what it looks like out of the box:

And I managed to modify most of it. But I just couldn’t get at that close button. It’s added directly by the Javascript. If it was in a Madcap CSS file – for example, as the background image on a div – then I could have overridden it with my own close button. But in the end I thought: sod it, if I can’t replace it I’ll just remove it. So here’s what I ended up with:

I know I’m biased, but I think it’s a big improvement. A little close button would have been nice, but I think most users know, or will quickly work out, that clicking away from the popup box makes it go away.

To style this up I used the following Javascript to add an override CSS file, which allows me to get at some of those hard-to-read Madcap styles:

$(document).ready(function(){
    ...
    //Append a link to the CSS file
    var newCSSlink=document.createElement('link');
    newCSSlink.setAttribute("href","Resources/StyleSheets/MCstylesOverrider.css");
    newCSSlink.setAttribute("rel","stylesheet");
    newCSSlink.setAttribute("type", "text/css");
    headElement = document.getElementsByTagName("head")[0];
    headElement.appendChild(newCSSlink);
    ...
});

This first line of the above code gives away that I’m using jQuery as an easy way to select and modify elements in the HTML. This just requires an extra Javascript file reference in the head of each page. If you use Javascript and you’re not familiar with jQuery, I’d strongly advise you have a look at it now!

Within my MCstylesOverrider.css file, the bit of CSS that removes the div containing the close button is:

div.MCKLinkBody div
{
    display: none;
}

Flare presents you with the old 80:20 rule. To get to a state where you’d be happy with the styling and behaviour of everything, you’d spend 20% of your time and effort getting 80% there, and then you’d spend the remaining 80% of the time finishing things off. For us pernickety perfectionists, Madcap could have made life a whole lot easier by making everything accessible and easy to change.

Message to software developers: when it comes to look and feel, less of the hard coding – please!

One reason for not declaring this information openly on the title page, was an expectation on the part of a few of our customers that each release of a software product should have its own release-specific manual – even if the release was just a bug fix release, where nothing requiring documentation was added or changed. I was determined to resist being forced into producing a new version of a manual where the only change was that “Release 7.5.2” changed to “Release 7.5.3” on the title page.

But the other (real) reason was that there had been times where, I have to admit, new releases of software went out without an updated manual, simply because of a lack of technical writing resource, and my title page coyness was driven by a desire on my part to avoid this being blindingly obvious to the customer. In this situation, you really don’t want to put “Release 9.5.0 – November 2005” on the title page of a manual that may accompany the 9.7.0 release of the software several months later.

But, thankfully, that situation has improved and earlier this year we started putting a simple document version number on the title page of our manuals:

Document version: 1

However, we ran into a problem with this. A simple version number leaves unanswered questions. Does the version number apply to that document, which gets updated throughout the life of a product, through various releases. That is, you wrote version 1 of the User’s Guide for the 1.0.0 release and when release 1.0.1 came around you didn’t write a new manual, you just made a couple of updates – so shouldn’t this be version 2? Or should it be another version 1, because it’s the first version of the manual for that particular release?

By this time we were logging all our new documents and documents updated for a specific release as records in a database. So, continuing the habit of a professional lifetime, I devised an obfuscated code based on database record for the relevant product, plus the record for the document, plus an eternally incrementing version number, to arrive at a unique identifier like:

Document version: 50.8.12

Still no date though. I was still extremely wary of openly declaring the publication date. Old habits die hard.

So, bringing things up to the present – and the reason for this blog post – my new thinking is: less obfuscation, more honesty. Right now the technical writing team is doing really well at keeping the documentation up to date. And my current belief is that if, in future, we start struggling to keep the documentation up to date, then making this obvious to the customer is probably a good thing. If up-to-date documentation is important to the customer, they’ll will raise this with the Support team, the Support team will raise that with me, and I can use that information to back up a request for more resource. If my company wants to keep its customers happy (which it does) then, in this situation, the chances are good that I’m then going to be able to get more resource when I need it.

My new plan for our title pages is to include information like this:

Document ID: 540
Revision number: 1
November 26, 2009

The document ID comes from our document database. Every time we create a brand new document or we update a document for a new release, we create a new document record and the revision number starts back at 1. Updates within a release don’t get a new document record, but the revision number increments.

We no longer need the old obfuscated code that we used to put on the copyright page, with details of who created and updated a document, because that information is captured in our database (and in SVN). The main change is adding the date. Like I said, I resisted doing this for a long time, but I’m now convinced that being open about the publication date is the right thing to do.

Having made this decision I thought it would be interesting to see what other software companies are doing. Here’s what I’ve found this evening after a quick, random and completely unscientific check of some publicly available software manuals. The following shows what document details I found on the title pages of the manuals I looked at, other than the company name, company details, product name, product release number and document title.

Citrix
No other details on title page. Copyright page included:
Document Code: June 3, 2009 (KKW)

Cisco
November 24, 2009
Text Part Number: OL-15574-01

IBM
SC09-4820-01

Oracle
E14481-01
February 2009

Adobe
No other details on title page. Copyright page included:
Part Number: 90081719 (07/07)

Microsoft Press
Traditional book publisher style title page and copyright page. No other details on title page. Copyright page contained lots of info, including ISBN, imprint numbers, names of all editors and indexer, then, at the bottom of the page:
Body Part No. X 12-41775

So what does this prove? Well it probably proves nothing, but it certainly suggests a general reluctance to declare how old the manual is on the title page – and there is still a fair amount of obfuscation going on out there.