There's a great example of user assistance that goes beyond the normal frontiers of a printed manual or an online help system on the STC Montreal blog. A current model Pentax digital SLR camera has a dedicated help button on its casing, and it displays brief context-sensitive messages on its screen.
This is a very valuable real-world example of embedded help - it shows that user assistance really can go anywhere it’s needed. Most tech writers I know would be thrilled to help their employers or their clients move beyond printed manuals or online help systems. It’s the companies that need to see that these possibilities exist, and then give us the chance to work with the engineers and interface designers to deliver the embedded help that can benefit users.
Wednesday, 24 December 2008
Monday, 22 December 2008
I like predictions like these
Scott Abel, The Content Wrangler himself, has asked Dave Kellogg, CEO of Mark Logic, for his top ten content technology predictions for 2009. You can read the article here.
Dave Kellogg's first prediction is that DITA will start making inroads as a document production standard in areas outside the relatively limited technical publications community. Dave's second prediction is that Microsoft SharePoint will continue to grow in importance and strength against other more cumbersome content management systems.
These two predictions are very interesting as far as I am concerned: I am the UK Authorised Reseller for DITA Exchange, a single source publishing and content collaboration platform for small, medium and large enterprises, which brings together the DITA open standard and Microsoft SharePoint Server. If Dave Kellogg is right I can look forward to a busy time in 2009!
Dave Kellogg's first prediction is that DITA will start making inroads as a document production standard in areas outside the relatively limited technical publications community. Dave's second prediction is that Microsoft SharePoint will continue to grow in importance and strength against other more cumbersome content management systems.
These two predictions are very interesting as far as I am concerned: I am the UK Authorised Reseller for DITA Exchange, a single source publishing and content collaboration platform for small, medium and large enterprises, which brings together the DITA open standard and Microsoft SharePoint Server. If Dave Kellogg is right I can look forward to a busy time in 2009!
Friday, 19 December 2008
Article reprint and survey last chance
An article I wrote two years ago has just appeared as the lead item in the December 2008 edition of Tieline, the newsletter for senior members and community leaders in the Society for Technical Communication. It's an article about running a survey using SurveyMonkey, and its publication is very timely: I am currently running another survey on SurveyMonkey, and it's about to close. So if you'd like to take part in the User Documentation Survey for 2008, you have got until midnight UK time on Sunday night (21st December) to do so.
Wednesday, 10 December 2008
Keeping up with contacts when the internet is "full"
The other day I took part in a conversation in the Ecademy blogosphere about how keeping in touch with your contacts became progressively more difficult as the number of contacts grew.
Now Seth Godin has suggested that keeping up with everyone, or with every article even in a "thin slice of a thin topic" is impossible. In his blog article "Warning: the internet is almost full" Seth comments that there is simply too much information and that even if the internet isn't physically full, we are.
Which brings me to an answer to the question of keeping up with contacts: you can't. You can offer a range of ways, through blogs, newsletters, web pages, tweets, and whatever, to let the people who are interested in what you do keep up with you. But if Seth Godin's right (he often is) and our attention span is under such attack, you're going to have to be doing really interesting things for anyone to be really interested.
Now I need to make sure that I do something interesting every day!
Now Seth Godin has suggested that keeping up with everyone, or with every article even in a "thin slice of a thin topic" is impossible. In his blog article "Warning: the internet is almost full" Seth comments that there is simply too much information and that even if the internet isn't physically full, we are.
Which brings me to an answer to the question of keeping up with contacts: you can't. You can offer a range of ways, through blogs, newsletters, web pages, tweets, and whatever, to let the people who are interested in what you do keep up with you. But if Seth Godin's right (he often is) and our attention span is under such attack, you're going to have to be doing really interesting things for anyone to be really interested.
Now I need to make sure that I do something interesting every day!
Sunday, 16 November 2008
User Documentation Survey 2008
Every so often I launch a survey about user documentation - sometimes it's specifically for a conference paper, and sometimes it's just as a small contribution to the growing body of knowledge in technical communications.
This time I have included three groups of questions: questions for people who create user documentation, questions for people who create technology products, and questions for the most important group of people of all - people who use technology products.
I am launching this survey as an open survey on the internet, and so I know any results will only be indicative, rather than representative of a particular group of users. However I do hope as many people as possible will take part.
I plan to publish the results in the first quarter of 2009, and because I have data from previous surveys (going back to 1999) I may be able to show some trends, particularly in terms of what kinds of documents are being produced.
Please take a few minutes to complete the survey - thank you.
This time I have included three groups of questions: questions for people who create user documentation, questions for people who create technology products, and questions for the most important group of people of all - people who use technology products.
I am launching this survey as an open survey on the internet, and so I know any results will only be indicative, rather than representative of a particular group of users. However I do hope as many people as possible will take part.
I plan to publish the results in the first quarter of 2009, and because I have data from previous surveys (going back to 1999) I may be able to show some trends, particularly in terms of what kinds of documents are being produced.
Please take a few minutes to complete the survey - thank you.
Wednesday, 12 November 2008
World Usability Day
I just wanted to post a reminder that Thursday 13th November 2008 is World Usability Day. If you're not sure what "usability" means, ask yourself this - why (to paraphrase a comment on the World Usability Day website) is a mobile phone more difficult to use than a door handle ?
Usability means making technology products easy to use, which in turn means designing products with the users' point of view in mind. That applies both to physical products, like mobile phones, and virtual products like computer software. Generally speaking, there is a tendency for the external design of technology products to reveal much too much of the inner workings of the product, which, although necessary, admirable, and often brilliant, are irrelevant to what the user needs to use the product for. I don't know of anyone who uses a hammer for knocking in nails who is particularly interested in the temperature of the furnace in which the hammer's head was forged. It may be interesting to someone, and it's certainly interesting for the manufacturer, but it's not relevant to the everyday tasks the hammer is used for. Unfortunately, irrelevant "furnace temperature" information abounds in the user literature for technology products.
I could go on about usability, and its general absence, for a long time. It's sad but true, but even the very finest user documentation can't compensate for a product that was designed without any consideration for its usability.
Follow the links for more on World Usability Day, and in particular on events in the UK.
Usability means making technology products easy to use, which in turn means designing products with the users' point of view in mind. That applies both to physical products, like mobile phones, and virtual products like computer software. Generally speaking, there is a tendency for the external design of technology products to reveal much too much of the inner workings of the product, which, although necessary, admirable, and often brilliant, are irrelevant to what the user needs to use the product for. I don't know of anyone who uses a hammer for knocking in nails who is particularly interested in the temperature of the furnace in which the hammer's head was forged. It may be interesting to someone, and it's certainly interesting for the manufacturer, but it's not relevant to the everyday tasks the hammer is used for. Unfortunately, irrelevant "furnace temperature" information abounds in the user literature for technology products.
I could go on about usability, and its general absence, for a long time. It's sad but true, but even the very finest user documentation can't compensate for a product that was designed without any consideration for its usability.
Follow the links for more on World Usability Day, and in particular on events in the UK.
Monday, 10 November 2008
Challenging linguistic theory isn't funny enough
One of the good things about science, is that it always knows it might be wrong. According to Karl Popper, a theory should be considered scientific if and only if it is falsifiable. New evidence can and should displace a prevailing theory, until the point at which even newer evidence emerges.
Linguists, for example, used to believe that language was culturally determined, and then along came Chomsky who presented evidence that it was an innate, genetically determined faculty. To borrow an analogy from Steven Pinker, humans have a language ability in the same way that spiders have a web-spinning ability.
While most of the broadcast and print media (such as the Telegraph)were widely reporting a "a list of the most irritating cliches" this weekend, taken from a new book about the English language, the really interesting item for linguists and language afficionados was hidden away elsewhere. On Saturday morning's travel programme "Excess Baggage" on BBC Radio 4, linguist Dan Everett was talking about his experiences with the Piraha people of the Amazon. If Everett is right, and the Piraha language does indeed lack some of the universal innate features that Chomsky ascribed to all languages, then perhaps it's time to review the prevailing theories in the light of the evidence. In academic circles, the debate about Everett's work had been going on for several years. But "at the end of the day" it's simply not entertaining - too much like "rocket science" I suppose.
Linguists, for example, used to believe that language was culturally determined, and then along came Chomsky who presented evidence that it was an innate, genetically determined faculty. To borrow an analogy from Steven Pinker, humans have a language ability in the same way that spiders have a web-spinning ability.
While most of the broadcast and print media (such as the Telegraph)were widely reporting a "a list of the most irritating cliches" this weekend, taken from a new book about the English language, the really interesting item for linguists and language afficionados was hidden away elsewhere. On Saturday morning's travel programme "Excess Baggage" on BBC Radio 4, linguist Dan Everett was talking about his experiences with the Piraha people of the Amazon. If Everett is right, and the Piraha language does indeed lack some of the universal innate features that Chomsky ascribed to all languages, then perhaps it's time to review the prevailing theories in the light of the evidence. In academic circles, the debate about Everett's work had been going on for several years. But "at the end of the day" it's simply not entertaining - too much like "rocket science" I suppose.
Sunday, 9 November 2008
Congratulations, Mr. Obama, Congratulations, USA.
I don't normally comment on politics, but this week has been exceptional. If I had been a US citizen last Tuesday I would probably have voted for Obama, but that is hardly unexpected, given that I am a university-educated, white, middle-class liberal with a white-collar job, living in a major urban centre.
From a professional point of view, I admire Obama's command of the English language. Courses on public speaking and writing to persuade can now use his speeches as exemplars of good practice. I was amused, and perhaps a little scared, by the attempt of the Republican Party to use "he's eloquent" as an insult.
In today's Independent on Sunday there is an analysis by Dr Max Atkinson on Obama's use of classical oratorical techniques particularly the three-part list, as in his victory speech:
[I haven't found this in the online edition of the paper, unfortunately.]
Another interesting aspect of Obama's campaign is the way he embraced technology not only to reach voters but to raise funds. I was going to comment on this, but I don't need to, as Conrad Taylor has already written an interesting article on his blog on the way the Obama team used online networking to raise money.
From a professional point of view, I admire Obama's command of the English language. Courses on public speaking and writing to persuade can now use his speeches as exemplars of good practice. I was amused, and perhaps a little scared, by the attempt of the Republican Party to use "he's eloquent" as an insult.
In today's Independent on Sunday there is an analysis by Dr Max Atkinson on Obama's use of classical oratorical techniques particularly the three-part list, as in his victory speech:
"Is there anyone out there who still doubts that America is a place where all things are possible;
who still wonders if the dream of our fathers is alive in our time;
who still questions the power of our democracy?"
[I haven't found this in the online edition of the paper, unfortunately.]
Another interesting aspect of Obama's campaign is the way he embraced technology not only to reach voters but to raise funds. I was going to comment on this, but I don't need to, as Conrad Taylor has already written an interesting article on his blog on the way the Obama team used online networking to raise money.
Sunday, 26 October 2008
Documentation standards? Who needs them?
A document called "BS ISO/IEC 26514:2008 Software and systems engineering: Requirements for designers and developers of user documentation" was published in June 2008, and is available from the BSI (though it's quite expensive to buy if you're an individual purchaser). The November 2008 edition of the STC's magazine Intercom focuses on standards in general and this new documentation standard in particular.
Now imagine this scenario: it's the documentation manager's cubicle in the development department of a medium-sized application software company. The VP of software development appears and asks the documentation manager this question: "Do you and your team have everything you need to make sure that our practices and procedures are compliant with the current ISO standard for user documentation?"
For most people involved in developing user documentation, the next scene would involve paramedics trying to resuscitate a documentation manager who had collapsed from shock.
The point I am trying to make with this lame attempt at humour is that with or without ISO standards, many small and medium sized organisations still regard user documentation as at best a marginal activity, or at worst as a necessary evil, and, especially in troubled economic times like these, as a cost centre that can and should be squeezed as much as possible. The idea that user documentation has any intrinsic value to a company, or that it is something important enough to be worthy of an international standard, is quite alien to many businesses.
I suspect that this sort of negative attitude towards user documentation is particularly prevalent here in the UK, where technical communications is hardly taught at all in higher education. (This may be because writing skills are not taught as a specific skill in secondary education in the UK, and instead are regarded as a key skill integrated across the whole curriculum - but that problem deserves a blog article of its own.) In the United States, in contrast, there are dozens of undergraduate and graduate programmes in technical communication, and there is also an expectation, absent from the UK HE sector, that engineering, computing and science undergraduates will all take at least one course in technical writing. But even in the USA, dismissive and derisory opinions of user documentation are still widespread.
I applaud the efforts being made by the STC in the United States to have the occupational designation of technical communicator recognised by the Bureau of Labor Statistics. I hope that here in the UK the ISTC will continue its efforts to ensure similar recognition, even though that means addressing both EU and UK authorities.
I am delighted that this ISO standard has been published, as it is a recognition of the importance of what technical writers do, and it gives added public legitimacy to our profession. In particular, I am pleased with the approach taken by the standard, of endorsing a task-based and user-focused approach to user documentation. This ISO standard could become a significant tool in improving the status of the documentation function in many companies.
Who needs documentation standards? We all do.
Now imagine this scenario: it's the documentation manager's cubicle in the development department of a medium-sized application software company. The VP of software development appears and asks the documentation manager this question: "Do you and your team have everything you need to make sure that our practices and procedures are compliant with the current ISO standard for user documentation?"
For most people involved in developing user documentation, the next scene would involve paramedics trying to resuscitate a documentation manager who had collapsed from shock.
The point I am trying to make with this lame attempt at humour is that with or without ISO standards, many small and medium sized organisations still regard user documentation as at best a marginal activity, or at worst as a necessary evil, and, especially in troubled economic times like these, as a cost centre that can and should be squeezed as much as possible. The idea that user documentation has any intrinsic value to a company, or that it is something important enough to be worthy of an international standard, is quite alien to many businesses.
I suspect that this sort of negative attitude towards user documentation is particularly prevalent here in the UK, where technical communications is hardly taught at all in higher education. (This may be because writing skills are not taught as a specific skill in secondary education in the UK, and instead are regarded as a key skill integrated across the whole curriculum - but that problem deserves a blog article of its own.) In the United States, in contrast, there are dozens of undergraduate and graduate programmes in technical communication, and there is also an expectation, absent from the UK HE sector, that engineering, computing and science undergraduates will all take at least one course in technical writing. But even in the USA, dismissive and derisory opinions of user documentation are still widespread.
I applaud the efforts being made by the STC in the United States to have the occupational designation of technical communicator recognised by the Bureau of Labor Statistics. I hope that here in the UK the ISTC will continue its efforts to ensure similar recognition, even though that means addressing both EU and UK authorities.
I am delighted that this ISO standard has been published, as it is a recognition of the importance of what technical writers do, and it gives added public legitimacy to our profession. In particular, I am pleased with the approach taken by the standard, of endorsing a task-based and user-focused approach to user documentation. This ISO standard could become a significant tool in improving the status of the documentation function in many companies.
Who needs documentation standards? We all do.
Tuesday, 14 October 2008
A bit of a grumble
It's happened to me so many times, I should be used to it by now, but I'm not. I meet people who are involved in product development, and when I try to talk to them about user documentation I get brushed-off with "It's OK, we do all our user documentation in-house." "That's great," I say, "how many technical writers do you have on staff?"
"Oh no," they reply, "we don't have any technical writers, the programmers (or the engineers, or whoever) do it themselves."
These are intelligent people, who wouldn't allow anyone other than an experienced and qualified accountant to prepare their company's balance sheet, or anyone other than a qualified and experienced lawyer to prepare their end-user licence agreement, but they'll happily entrust preparing their user documentation to someone without any relevant experience or qualifications!
"Oh no," they reply, "we don't have any technical writers, the programmers (or the engineers, or whoever) do it themselves."
These are intelligent people, who wouldn't allow anyone other than an experienced and qualified accountant to prepare their company's balance sheet, or anyone other than a qualified and experienced lawyer to prepare their end-user licence agreement, but they'll happily entrust preparing their user documentation to someone without any relevant experience or qualifications!
Sunday, 5 October 2008
Bad news for UGC from "Private Eye"
User-generated content (UGC) is all the rage these days. It's at the heart of many social networking web sites, and is increasingly becoming monetized as well. For example, there are web sites where you can upload a video from your phone, and earn a very small amount of money each time someone else pays to download your video.
For people working in technical publications UGC presents a bit of a paradox. On the one hand, gathering feedback from real users is always valuable and helps build a user community (and from a commercial viewpoint builds customer loyalty as well).
On the other hand, companies have a degree of responsibility for goods they sell, and they therefore need to provide accurate and authoritative instructions and reference material. An open and unmoderated user forum or Wiki might not always be the best vehicle for providing that kind of information.
Many advocates of UGC in general, and of wikis in particular, are fond of claiming that over time the Wiki will always be right, because anyone who finds an error will correct it. To my mind this assumes a degree of altruism which might not always be present, and so should not really be relied on. Wikipedia for example may be a useful source, but only if it is used with the same degree of critical evaluation as any other source.
An interesting example of the way that Wikipedia might be misused and might inadvertently contribute to the perpetuation of false information comes from the current edition of Private Eye, the satirical British magazine (Private Eye, no. 1220, 3-16 Oct. 2008). In an attack on the sloppy research practices of one sports journalist on a national daily newspaper, Anatole Kaletsky includes the following story in his "Hackwatch" column:
This may just be an amusing story, and I don't know how the community of editors on Wikipedia will handle it. (They probably did not foresee that something that was clearly a spoof would be used so uncritically by someone from the mainstream media.) But I see this also as a warning against relying too heavily on any user generated content.
For people working in technical publications UGC presents a bit of a paradox. On the one hand, gathering feedback from real users is always valuable and helps build a user community (and from a commercial viewpoint builds customer loyalty as well).
On the other hand, companies have a degree of responsibility for goods they sell, and they therefore need to provide accurate and authoritative instructions and reference material. An open and unmoderated user forum or Wiki might not always be the best vehicle for providing that kind of information.
Many advocates of UGC in general, and of wikis in particular, are fond of claiming that over time the Wiki will always be right, because anyone who finds an error will correct it. To my mind this assumes a degree of altruism which might not always be present, and so should not really be relied on. Wikipedia for example may be a useful source, but only if it is used with the same degree of critical evaluation as any other source.
An interesting example of the way that Wikipedia might be misused and might inadvertently contribute to the perpetuation of false information comes from the current edition of Private Eye, the satirical British magazine (Private Eye, no. 1220, 3-16 Oct. 2008). In an attack on the sloppy research practices of one sports journalist on a national daily newspaper, Anatole Kaletsky includes the following story in his "Hackwatch" column:
IDLY sabotaging the user-generated online encyclopedia Wikipedia following the UEFA cup draw back in August, a user of the b3ta web forum going by the name of "godspants" made a few amendments to the entry for Cypriot team Omonia Nicosia.
He (or she) noted that they were sponsored by Natasha Kaplinsky, that their former players included Jean Claude Van Damme and Richard Clayderman, and claimed that "A small but loyal group of fans are lovingly called 'The Zany Ones' - they like to wear hats made from discarded shoes and have a song about a little potato." As you do.
Writing up his pre-match report on Omonia's match against Manchester City for the Daily Mirror on 18 September, sports hack David Anderson decided to do some in-depth research. Thus it was that Mirror readers were informed that City manager "Mark Hughes will not tolerate any slip-ups against the Cypriot side, whose fans are known as the 'Zany Ones' and wear hats made from shoes".
Brilliantly, by the rules of Wikipedia - which relies on "verifiablility - whether readers are able to check that material added has already been published by a reliable, third-party source" such as "mainstream newspapers" - this is now officially true.
This may just be an amusing story, and I don't know how the community of editors on Wikipedia will handle it. (They probably did not foresee that something that was clearly a spoof would be used so uncritically by someone from the mainstream media.) But I see this also as a warning against relying too heavily on any user generated content.
Monday, 22 September 2008
Good news for DITA from Edinburgh
I have just returned from a trip to the European UA Conference which was held this year in Edinburgh. There were plenty of speakers who mentioned DITA, including one delegate who demonstrated how her company had developed a bespoke solution using DITA and a WordPress blog.
There was also a "fringe meeting" (if you hold a conference in Edinburgh you just have hold a fringe meeting!!) in which Tony Self of Hyperwrite introduced delegates to the DITA Help technical sub-committee which he currently chairs.
I was at the conference as an Exhibitor for DITA Exchange, and I was kept very busy with enquiries at my stand. My vendor presentation went well and the live internet connection to a Microsoft SharePoint Server located in Denmark actually worked.
But the best news for people concerned about the slow pace of DITA adoption is that in a pre-conference survey which asked delegates which help technology interests them for the future more than a third of delegates chose DITA. I think that's an impressive and reassuring statistic.
There was also a "fringe meeting" (if you hold a conference in Edinburgh you just have hold a fringe meeting!!) in which Tony Self of Hyperwrite introduced delegates to the DITA Help technical sub-committee which he currently chairs.
I was at the conference as an Exhibitor for DITA Exchange, and I was kept very busy with enquiries at my stand. My vendor presentation went well and the live internet connection to a Microsoft SharePoint Server located in Denmark actually worked.
But the best news for people concerned about the slow pace of DITA adoption is that in a pre-conference survey which asked delegates which help technology interests them for the future more than a third of delegates chose DITA. I think that's an impressive and reassuring statistic.
Tuesday, 9 September 2008
A few of my unfavourite things in Microsoft Word
I have enjoyed a long relationship with Microsoft Word for Windows, and I would describe myself as a reluctant admirer. As a heavy-duty user of Word, I understand that I am not using it in the way it was designed to be used, so I have modified my expectations accordingly. As well as my expectations, I have also learned to modify some of Word’s default settings so that I can have a little more control over its behaviour. As I have recently started working with Word 2007, I am going to describe some my my favourite tweaks – the adjustments that I make to disable my unfavourite features in Word 2003, and what the equivalent adjustments are in Word 2007.
Read the rest of this article on my web site...
Read the rest of this article on my web site...
Tuesday, 19 August 2008
Is editing a romantic profession?
I don't often do film reviews, but I have to mention something I watched the other night on DVD. Billed as a "sleek, sassy romantic comedy", Suburban Girl had, for me at least, a fascinating occupational setting - the world of book editing and publishing.
The film stars Sarah Michelle Gellar and Alec Baldwin as a pair of generation-bridging lovers - a young woman with a much older man. Gellar plays a lowly Associate Editor in a small publishing company while Baldwin is the Editor-in-Chief of a much bigger publishing house. Gellar spends much of the film poring over typed manuscripts, scribbling notes to authors and writing reports for her managers. The film itself is interrupted by "editorial" comments to the audience, introducing different chapters of the story.
Gelllar is not the only actor whose subsequent career has risked being overshadowed by a long-running successful TV role, but she is good enough her as the innocent from out of town to make you almost forget the vampires in her past. She is at her best when her character gets embarassingly drunk at a literary party.
Baldwin plays the successful unmarried man with a photo album full of previous lovers who treats his women badly. Not an entirely likeable character, but I found him more the more believable actor.
Overall, I'm afraid the film itself didn't really succeed for me, as the plot was very thin and the dramatic development of Gellar's character was weak and not entirely convincing.
The film stars Sarah Michelle Gellar and Alec Baldwin as a pair of generation-bridging lovers - a young woman with a much older man. Gellar plays a lowly Associate Editor in a small publishing company while Baldwin is the Editor-in-Chief of a much bigger publishing house. Gellar spends much of the film poring over typed manuscripts, scribbling notes to authors and writing reports for her managers. The film itself is interrupted by "editorial" comments to the audience, introducing different chapters of the story.
Gelllar is not the only actor whose subsequent career has risked being overshadowed by a long-running successful TV role, but she is good enough her as the innocent from out of town to make you almost forget the vampires in her past. She is at her best when her character gets embarassingly drunk at a literary party.
Baldwin plays the successful unmarried man with a photo album full of previous lovers who treats his women badly. Not an entirely likeable character, but I found him more the more believable actor.
Overall, I'm afraid the film itself didn't really succeed for me, as the plot was very thin and the dramatic development of Gellar's character was weak and not entirely convincing.
Tuesday, 12 August 2008
Beware the Default Manual
Thomas Barker, in his book Writing Software Documentation, uses the term “the default manual” to describe a user’s guide that is organised according to features, rather than tasks. This sort of user’s guide has a chapter for each menu in a software program, and a section for each command. (For hardware, which Barker’s book doesn’t cover, it would describe every switch and button.) Barker rightly explains that this sort of manual is not really very useful for users. The information in a default manual, and in particular the way the information is organised, bears little or no resemblance to what the average user needs to do in their everyday working life. Like the old (and unfair) joke about Microsoft Customer Support, the information given is totally accurate but absolutely useless. In short, default manuals are the sort of things that give technical writing a bad name.
Like Barker, I believe in the importance of user focused documentation, and try never to write default manuals. Unfortunately a lot of my customers have yet to understand the difference between effective user assistance on the one hand, and the only kind of user manual they have ever been exposed to on the other, and the default manual is what they ask me to produce. I don’t always succeed in convincing them that their users deserve something better.
Barker does not discuss why default manuals are so prevalent. I can think of plenty of reasons. First of all default manuals appear to be quick and easy to write. They are based on the product’s features, so the structure of commands in user menus offers an instant structure for the manual, and an instant checklist to ensure that every thing is mentioned. Since they describe program features rather than user actions they are easy to write. Even the most junior programmer on the team knows that the New command on the File menu creates a new file. That’s why so many default manuals are indeed written by the most junior programmer on the team.
Default manuals reflect the developer’s world-view, or more accurately the development manager’s world-view. The development manager rarely sees any feedback or comments from customers, and has probably never spoken to a real life customer either. For development managers, thinking about users doesn’t just take time and effort, it requires a degree of objectivity and critical detachment from their work that was never part of their job descriptions. They have goals to achieve which are stated in terms of objects coded, features implemented, and overtime hours saved, not in terms of user task fulfilment or customer satisfaction. Those things have no relevance to their jobs or to their end-of-year bonuses.
The lure of the familiar is also significant. Like travellers’ tales of exotic creatures and peculiar peoples, the idea that a different and better way of writing user manuals might exist is regarded with more than a little scepticism by many in the developer community. Default manuals are all they have ever known.
A third reason for the popularity of default manuals is that they are an easy way of demonstrating that the development team’s “contractual obligations” have been met. I am thinking here of “contractual” in the broadest possible sense, and including not only written undertakings to external customers but also internal agreements and understandings with stakeholders within an organisation.
Default manuals are popular because they appear temptingly simple and easy, and because they can be shown to correlate directly to the product features. They can be written cheaply by an existing member of the team who won’t “bother” other developers with questions that waste their valuable time. Once they’ve been done, the development manager can tick several boxes at once – there is evidence that all the required features are there, the program’s features have been checked by a competent person, and hey presto, there are user manuals as well. In this scenario no-one is surprised or worried by the fact that the manuals will never be opened, let alone read. That was never anyone’s intention.
Fighting back against the default manual culture is a challenging and difficult undertaking, especially if you are the only professional writer around. But it is a noble cause and one that all technical writers should pledge themselves to.
Thursday, 7 August 2008
How did they design Office 2007?
I have just read a fascinating interview with one of the people responsible for designing the ribbon interface of Office 2007. (Thanks to Peter Bogaards of InfoDesign - Understanding by design for providing the link - Peter always recommends excellent material.) I know a large number of technical writers who are heavy-duty users of Microsoft Word, and the ribbon interface was one of the new features of Word 2007 that many technical writers of my acquaintance did not like at all when it was first launched. A common early reaction was something like: "just when we got used to where all the commands were in Word 2003, Microsoft went and changed everything again!" Opinions of Word 2007 have mellowed somewhat over the last year or so, as professional technical writers have got used to the new interface, and developed efficient ways of working with it.
The interview itself is by Dan Harrelson of Adaptive Path, and in it he speaks to Jensen Harris, Group Program Manager of Microsoft’s Office User Experience team. The first thing that is clear from what Jensen says is that the heavy-duty professional Word user was never a focus of the Microsoft Office development effort. In fact, Harris says, it was ordinary users who were central to their thinking: "...we wanted normal people to be able to make beautiful, stunning documents and presentations. We wanted the average user to have access to professional-level results with fewer steps than in the past." Harris goes on to extol the virtues of being able to "beautify" a picture in your document with "great-looking designs", which you can now do with Office 2007's graphics engine. This type of aesthetic question is not usually uppermost in the minds of most professional technical writers. We are more interested in mundane stuff, like consistent application of formatting styles, paragraph or heading numbering that doesn't have a mind of its own, pagination that stays put, indexing, cross-referencing, tables of contents, and so on. In fact, most professional writers are really most concerned with getting the content right - making sure that the words themselves are accurate, concise, appropriate, effective - so even the word processing features we are interested in are actually a distraction for us. That may be why some technical writers get so annoyed when Word does unexpected things.
The most fascinating feature of the interview is the description Harris getting developers to observe usability tests.
The interview itself is by Dan Harrelson of Adaptive Path, and in it he speaks to Jensen Harris, Group Program Manager of Microsoft’s Office User Experience team. The first thing that is clear from what Jensen says is that the heavy-duty professional Word user was never a focus of the Microsoft Office development effort. In fact, Harris says, it was ordinary users who were central to their thinking: "...we wanted normal people to be able to make beautiful, stunning documents and presentations. We wanted the average user to have access to professional-level results with fewer steps than in the past." Harris goes on to extol the virtues of being able to "beautify" a picture in your document with "great-looking designs", which you can now do with Office 2007's graphics engine. This type of aesthetic question is not usually uppermost in the minds of most professional technical writers. We are more interested in mundane stuff, like consistent application of formatting styles, paragraph or heading numbering that doesn't have a mind of its own, pagination that stays put, indexing, cross-referencing, tables of contents, and so on. In fact, most professional writers are really most concerned with getting the content right - making sure that the words themselves are accurate, concise, appropriate, effective - so even the word processing features we are interested in are actually a distraction for us. That may be why some technical writers get so annoyed when Word does unexpected things.
The most fascinating feature of the interview is the description Harris getting developers to observe usability tests.
"When you want to convince a developer to help you make a change to the product, nothing is as compelling as bringing the developer into the lab and having them watch people fail. (Video also works well if you can’t bring the developer to the lab.)
Putting a human face on a failure really drives home why it’s important to improve usability, and helps everyone to visualize concretely whom we’re building the software for. Any developer worth her weight wants to do the right thing for her users, and so you usually just need to show them a test or two, and you’ll find that they are much more willing to help you. We bring developers and testers into our user research labs as frequently as possible."
This is good to know, for several reasons. It's good to know that Microsoft use usability testing, and takes note of user research findings. It's even better to know that in this team at least, developers were engaged with the testing process. Telling companies reluctant to undertake usability testing that "this is what Microsoft do" may have a positive effect.
But it's also clear that Microsoft did not have heavy-duty users in mind when it developed Office 2007, which is why, in its standard "out-of-the-box" implementation, Word 2007 is still not the best choice for large scale technical publications.
Tuesday, 5 August 2008
Holidays and spam
Last week I disconnected myself from the Internet, got in the car and headed north for a week's holiday in the English countryside. (We stayed at Wheeldon Trees Farm, near Buxton, which is in the Peak District National Park.)
Apart from the fine weather (we were lucky), the beautiful countryside, the excellent country pubs, and the interesting sites to visit, the holiday had another added bonus. There was no mobile reception for our network at least where we were staying. This meant I couldn't even check my email to see how the world was faring without me.
The world survived. When I returned to London I found my email mailboxes jammed with over 1,600 messages in just 7 days - and this number excludes most of the mailing lists I subscribe to. That looked like far more emails than I usually receive, and I was worried that I might have chosen a particularly busy week to go away.
On closer examination, I found that my spam filters had filtered out around 1,400 messages into easily deletable folders, leaving about 200 legitimate messages to look at. These messages included newsletters, circulars, and adverts - and some spam emails that had slipped through the filters - so the actual number of emails that were for me personally was just a couple of dozen. So despite first impressions, we had picked a quiet week for our holiday after all.
I know all the reasons for spam, and I know how to ignore the scams and phishing attempts. My email addresses are out there in the wild, and I can't stop them. On an individual level, I know my ISP and mail software have pretty good filters that save me plenty of time. What worries me is the danger that the sheer volume of electronic junk may one day overload the Internet completely.
Apart from the fine weather (we were lucky), the beautiful countryside, the excellent country pubs, and the interesting sites to visit, the holiday had another added bonus. There was no mobile reception for our network at least where we were staying. This meant I couldn't even check my email to see how the world was faring without me.
The world survived. When I returned to London I found my email mailboxes jammed with over 1,600 messages in just 7 days - and this number excludes most of the mailing lists I subscribe to. That looked like far more emails than I usually receive, and I was worried that I might have chosen a particularly busy week to go away.
On closer examination, I found that my spam filters had filtered out around 1,400 messages into easily deletable folders, leaving about 200 legitimate messages to look at. These messages included newsletters, circulars, and adverts - and some spam emails that had slipped through the filters - so the actual number of emails that were for me personally was just a couple of dozen. So despite first impressions, we had picked a quiet week for our holiday after all.
I know all the reasons for spam, and I know how to ignore the scams and phishing attempts. My email addresses are out there in the wild, and I can't stop them. On an individual level, I know my ISP and mail software have pretty good filters that save me plenty of time. What worries me is the danger that the sheer volume of electronic junk may one day overload the Internet completely.
Monday, 21 July 2008
Hurrah for Dr Johnson
Dr Samuel Johnson, patron saint of this blog, earned an honourable mention in yesterday's Independent on Sunday. Katy Guest wrote in praise of blogging as a way to quash rumours and gossip. In "What's the best way to keep a secret? Tell the world the details on your website" she wrote about a Lancashire millionaire, Gary Dean, who has published full details of his divorce settlement on his blog to stop people talking about it behind his back.
Katy Guest paraphrased Dr Johnson for the "internet age":
I'm not sure that I quite follow the parallel here, nor I am quite happy with the suggestion that every blogger is a "blockhead" in any sense of the word, but I raised a small hurrah for my favourite quote from my favourite "harmless drudge" getting a few nanoseconds of fame.
Katy Guest paraphrased Dr Johnson for the "internet age":
Samuel Johnson said: "No man but a blockhead ever wrote, except for money." This could be rewritten for the internet age. No man but a blogger ever wrote about his private life online.
I'm not sure that I quite follow the parallel here, nor I am quite happy with the suggestion that every blogger is a "blockhead" in any sense of the word, but I raised a small hurrah for my favourite quote from my favourite "harmless drudge" getting a few nanoseconds of fame.
Saturday, 19 July 2008
Some places still available for distance learning MA courses in Communications
I am told by my colleagues at Sheffield Hallam University that there are a few places still available for the distance learning MA programme in Professional Communications for the autumn session which begins in September.
The programme offers four courses of study, each with a slightly different emphasis, and all with some shared modules:
Corporate Communication, focusing on communication within organisations, including corporate image, ethics and public relations, looking at both theoretical and practical aspects of the communications process;
E-Communication designed to give you a thorough understanding of human and digital communication, and the growing importance of the web and other contemporary technologies as tools of corporate communication;
Professional Communication a flexible award in terms of the option modules combining theory and practice, and including document design, persuasive communication and communication strategy;
Technical Communication focusing on the means and methods of disseminating technical information and instruction to varied audiences, looking at the role of the technical communicator in a wide variety of industrial and corporate contexts.
I am an Associate Lecturer for the Technical Communications MA course, as well as a graduate of the course myself. I'd be very happy to answer any questions about the course.
The programme offers four courses of study, each with a slightly different emphasis, and all with some shared modules:
Corporate Communication, focusing on communication within organisations, including corporate image, ethics and public relations, looking at both theoretical and practical aspects of the communications process;
E-Communication designed to give you a thorough understanding of human and digital communication, and the growing importance of the web and other contemporary technologies as tools of corporate communication;
Professional Communication a flexible award in terms of the option modules combining theory and practice, and including document design, persuasive communication and communication strategy;
Technical Communication focusing on the means and methods of disseminating technical information and instruction to varied audiences, looking at the role of the technical communicator in a wide variety of industrial and corporate contexts.
I am an Associate Lecturer for the Technical Communications MA course, as well as a graduate of the course myself. I'd be very happy to answer any questions about the course.
Tuesday, 15 July 2008
This blog has moved
Correction 19th July 2008
I have moved back now, but with my own domain name. You can now find this blog at http://www.theblockheadblog.co.uk
I hope you like the new colours. :-)
Original message 15th July 2008
If you followed a link to theblockheadblog.blogspot.com you will have found a redirection notice to send you here. I've moved my blog to a new home on my own ISP's server, rather than on Blogspot. This is an experiment, and I'll decide in a few weeks whether I am going to keep it this way. I am still using Blogger software to write new posts, for the time being at least.
I've lost a couple of features, such as the blogroll and the Technorati links, and if you have any ideas on how I can get those features back, or any suggestions on alternative blogging software I could use, please let me know.
I have moved back now, but with my own domain name. You can now find this blog at http://www.theblockheadblog.co.uk
I hope you like the new colours. :-)
Original message 15th July 2008
If you followed a link to theblockheadblog.blogspot.com you will have found a redirection notice to send you here. I've moved my blog to a new home on my own ISP's server, rather than on Blogspot. This is an experiment, and I'll decide in a few weeks whether I am going to keep it this way. I am still using Blogger software to write new posts, for the time being at least.
I've lost a couple of features, such as the blogroll and the Technorati links, and if you have any ideas on how I can get those features back, or any suggestions on alternative blogging software I could use, please let me know.
Monday, 14 July 2008
The Lure of Modular Writing
Since I started being more involved with a specific DITA product, I am seeing opportunities for modular writing everywhere. This may be a case of "when the only tool you have is a hammer, then every problem looks like a nail", but every new prospective technical writing assignment looks to me like an opportunity for a modular approach.
A modular approach to technical writing doesn't mean adopting a particular technology or tool, it means adopting a different way of thinking about what you write. In an August 2001 article in Technical Communication, Michael Priestley of IBM urged writers to "ditch the book as the basic structure" in order to maximise the potential benefits of content reuse using DITA.
But even without adopting DITA, thinking of content in a more granular way can have benefits. Don't think I'm writing "three books for this client's product", rather think "I'm writing seventy-five topics". Ask yourself how this material can be split up into smaller stand-alone portions ("chunks")? Where are the concepts, and where are the procedures? What user steps are needed in more than one situation? What material needs to be repeated in every publication?
You can then decide separately how to assemble those topics into whatever publications and formats are most suitable. There are dozens of different tools to help make that job easier, and each tool has its own pros and cons.
I know that many technical writers think that a modular approach can be artificial and limiting, but I take the opposite view. It liberates technical writers from worrying about the presentation of technical information, so that they can concentrate on getting the content right - timely, accurate, concise, and relevant, and del=ivered as close as possible to the point of need.
A modular approach to technical writing doesn't mean adopting a particular technology or tool, it means adopting a different way of thinking about what you write. In an August 2001 article in Technical Communication, Michael Priestley of IBM urged writers to "ditch the book as the basic structure" in order to maximise the potential benefits of content reuse using DITA.
But even without adopting DITA, thinking of content in a more granular way can have benefits. Don't think I'm writing "three books for this client's product", rather think "I'm writing seventy-five topics". Ask yourself how this material can be split up into smaller stand-alone portions ("chunks")? Where are the concepts, and where are the procedures? What user steps are needed in more than one situation? What material needs to be repeated in every publication?
You can then decide separately how to assemble those topics into whatever publications and formats are most suitable. There are dozens of different tools to help make that job easier, and each tool has its own pros and cons.
I know that many technical writers think that a modular approach can be artificial and limiting, but I take the opposite view. It liberates technical writers from worrying about the presentation of technical information, so that they can concentrate on getting the content right - timely, accurate, concise, and relevant, and del=ivered as close as possible to the point of need.
Sunday, 13 July 2008
Distance Learning at SHU mentioned in "The Independent"
Last Thursday's (10th July 2008) "Independent" newspaper carried an article about the impact of distance-learning postgraduate courses, Distance learning is helping workers' careers – and their pockets, too. The article spotlights the growing popularity of distance-learning MA courses for people trying to get ahead in the workplace, where an undergraduate degree is often no longer enough.
One of the students interviewed in the article is a graduate of the Corporate Communications MA course at Sheffield Hallam University (SHU). The student said she was "more confident knowing the theory that underpins what I'm doing every day", which is a key reason for undertaking academic study related to one's professional life. Corporate Communications is one of the four streams in the MA Programme in Professional Communication at SHU. The others are e-Communication, Professional Communication, and Technical Communication. I am of course, an interested party - as I may have mentioned before in this blog, I am an Associate Lecturer for the Technical Communications course.
One of the students interviewed in the article is a graduate of the Corporate Communications MA course at Sheffield Hallam University (SHU). The student said she was "more confident knowing the theory that underpins what I'm doing every day", which is a key reason for undertaking academic study related to one's professional life. Corporate Communications is one of the four streams in the MA Programme in Professional Communication at SHU. The others are e-Communication, Professional Communication, and Technical Communication. I am of course, an interested party - as I may have mentioned before in this blog, I am an Associate Lecturer for the Technical Communications course.
Wednesday, 9 July 2008
Declining writing standards?
Someone on LinkedIn Answers asked the question "Has writing gone the way of the Dodo?" and wrote that he didn't mean that writing was extinct, just that standards of business writing appear to have declined. He provoked a lot of responses from writers, and his question certainly hit a nerve with me, so here's what I wrote in reply:
"Mass literacy has been replaced by mass communication, and many people don't read any more they just watch or listen. I don't think you can master the complexities of written language - particularly written English - without reading widely or studying deliberately.
Modern school education hasn't done a good job of teaching the mechanics of English, and I have taught non-specialist undergraduate university students who have come to a class on writing and been unable to explain what an adjective is. "I didn't think this class was going to be about grammar", said one. But if you can't tell what the parts of a sentence are how can you ever hope to write a meaningful one? These students had clearly passed their GCSEs and A-levels even though they didn't appear to know much about language, and without devaluing their achievements it does suggest that the English language standards expected by examiners can't be that high.
Technology and market forces also play their part in keeping down the value of writing. There are people out there who will write you 250 words of SEO-focused junk copy for about 5p, making it difficult for professional writers of any kind to charge reasonable rates. My own approach to technical communication makes this aspect of the problem even worse, as I generally find myself telling clients they need to publish fewer words. Shouldn't that be cheaper?
I am constantly amazed that although people who have Microsoft Excel on their Windows PC don't immediately think that they can be accountants, everyone who has a copy of Microsoft Word thinks they can be a writer. Worse still, everyone who has a copy of Microsoft Word appears to think that they can be a typographer as well (and don't get me started on how "ICT Skills" are being taught in UK schools).
So I'd blame the decline in writing standards on a combination of a number of different expectations all coming together - people are offering very cheap writing services, so it's not worth paying for; there's a tool on my computer that "does" writing so it must be easy; I passed my exams at school without making much of an effort at writing skills so why should I bother to make an effort now?"
"Mass literacy has been replaced by mass communication, and many people don't read any more they just watch or listen. I don't think you can master the complexities of written language - particularly written English - without reading widely or studying deliberately.
Modern school education hasn't done a good job of teaching the mechanics of English, and I have taught non-specialist undergraduate university students who have come to a class on writing and been unable to explain what an adjective is. "I didn't think this class was going to be about grammar", said one. But if you can't tell what the parts of a sentence are how can you ever hope to write a meaningful one? These students had clearly passed their GCSEs and A-levels even though they didn't appear to know much about language, and without devaluing their achievements it does suggest that the English language standards expected by examiners can't be that high.
Technology and market forces also play their part in keeping down the value of writing. There are people out there who will write you 250 words of SEO-focused junk copy for about 5p, making it difficult for professional writers of any kind to charge reasonable rates. My own approach to technical communication makes this aspect of the problem even worse, as I generally find myself telling clients they need to publish fewer words. Shouldn't that be cheaper?
I am constantly amazed that although people who have Microsoft Excel on their Windows PC don't immediately think that they can be accountants, everyone who has a copy of Microsoft Word thinks they can be a writer. Worse still, everyone who has a copy of Microsoft Word appears to think that they can be a typographer as well (and don't get me started on how "ICT Skills" are being taught in UK schools).
So I'd blame the decline in writing standards on a combination of a number of different expectations all coming together - people are offering very cheap writing services, so it's not worth paying for; there's a tool on my computer that "does" writing so it must be easy; I passed my exams at school without making much of an effort at writing skills so why should I bother to make an effort now?"
Friday, 4 July 2008
A custard cream? That's neet!
The latest edition of the Concise Oxford English Dictionary (OED) was published this week, and there have been a spate of articles about some of the new words that are in the dictionary for the first time, including custard cream and neet. The OED is a repository of the words we use - it's a descriptive rather than a prescriptive publication. Our current preoccupations with the economy are therefore well represented, with sub-prime, non-dom, and boiler room all getting in for the first time.
The regular updates of the OED are ignored or mocked by people who have an authoritarian attitude to language (and probably to everything else in their lives).
I'll let you look up the new financial words for yourselves, but I'll explain that a custard cream is a type of biscuit (cookie, if you speak American English) with a vanilla cream filling. It's the iconic snack offered to donors after giving blood, so much so that the National Blood Service in the UK have a sticker with the slogan "I'd give my right arm for a custard cream"!
A neet, on the other hand is less tasty then a cream-filled biscuit. It's an acronym to describe a young person "not in employment, education, or training".
The regular updates of the OED are ignored or mocked by people who have an authoritarian attitude to language (and probably to everything else in their lives).
I'll let you look up the new financial words for yourselves, but I'll explain that a custard cream is a type of biscuit (cookie, if you speak American English) with a vanilla cream filling. It's the iconic snack offered to donors after giving blood, so much so that the National Blood Service in the UK have a sticker with the slogan "I'd give my right arm for a custard cream"!
A neet, on the other hand is less tasty then a cream-filled biscuit. It's an acronym to describe a young person "not in employment, education, or training".
Thursday, 3 July 2008
Adobe's PDF now an ISO standard
Adobe's Portable Document Format has now become an ISO standard. This means that an independent non-commercial organisation is now the custodian of the technology standard. Read the ISO's press release in full.
This is similar to way that IBM handed over the DITA standard to the custody of OASIS.
This is similar to way that IBM handed over the DITA standard to the custody of OASIS.
Monday, 30 June 2008
Heaven depends on your point of view
Mike Hughes has a great joke for technical writers to enjoy on his User Assistance blog.
Quite a few developers I know won't like it at all!
The real point is that most technical communicators could really make huge contributions, if they were only allowed to. In the meantime, enjoy the joke.
Quite a few developers I know won't like it at all!
The real point is that most technical communicators could really make huge contributions, if they were only allowed to. In the meantime, enjoy the joke.
Friday, 20 June 2008
Writer and... what?
An STC colleague spotted an advert on the Washington DC "craigslist" message board that takes the idea of combining careers to new heights - or depths. In what appears to be a serious advert for a copywriter to work on marketing materials - a post requiring a degree in Journalism or similar and that reports directly to the "Senior Vice President of Sales and Marketing" - there is what the advertiser refers to as "a twist": "while you are writing copy you will also fill the role of security guard".
Reassuringly, the advertiser adds "You won’t carry a gun". The advert goes on to explain "The security guard spends most of the shift seated at the reception desk, and there will be very minimal security duties. Practically the entire shift you will be able to focus on writing copy – you’ll just happen to be wearing a uniform." (You can read the original advert here.)
We've all heard stories of successful writers and artists who began their adult lives by working in a series of unskilled jobs until they were recognised professionally. Some people do have two careers in parallel, like the American poet Wallace Stevens who had a lifetime career as an insurance company executive. But I've never come across an actual job description that said "copywriter and security guard" before.
This advert would be very funny if it wasn't betraying a disturbingly arrogant and condescending attitude to writers - and to security guards. "Your job looks easy, so it can't be important. You just sit around most of the day so you're not "doing" anything."
I hope this company gets the copywriter - and the security - it deserves.
Reassuringly, the advertiser adds "You won’t carry a gun". The advert goes on to explain "The security guard spends most of the shift seated at the reception desk, and there will be very minimal security duties. Practically the entire shift you will be able to focus on writing copy – you’ll just happen to be wearing a uniform." (You can read the original advert here.)
We've all heard stories of successful writers and artists who began their adult lives by working in a series of unskilled jobs until they were recognised professionally. Some people do have two careers in parallel, like the American poet Wallace Stevens who had a lifetime career as an insurance company executive. But I've never come across an actual job description that said "copywriter and security guard" before.
This advert would be very funny if it wasn't betraying a disturbingly arrogant and condescending attitude to writers - and to security guards. "Your job looks easy, so it can't be important. You just sit around most of the day so you're not "doing" anything."
I hope this company gets the copywriter - and the security - it deserves.
Speaking on DITA
I've been invited to speak at a British Computer Society event on XML and DITA in London on 15th July. Details and registration at: http://tinyurl.com/4ayvjb
Wednesday, 18 June 2008
DITA Exchange discussed on an MSDN blog
John Mullinax of Microsoft has discussed DITA Exchange in an interview with Steffen Fredericksen on his MSDN blog under the title Democratizing DITA
This presents a very interesting overview of DITA Exchange, and discusses how the forthcoming Office Business Application for Microsoft Word 2007 will make it even easier for subject matter experts and other contributors to collaborate on creating DITA compliant technical documentation.
This presents a very interesting overview of DITA Exchange, and discusses how the forthcoming Office Business Application for Microsoft Word 2007 will make it even easier for subject matter experts and other contributors to collaborate on creating DITA compliant technical documentation.
Thursday, 12 June 2008
David Farbey (Dannywell Ltd.) to represent DITA Exchange in the UK
I am delighted to announce that as of June 2008 my company, Dannywell Ltd., has been appointed as the first Authorised Reseller in the UK for DITA Exchange. DITA Exchange is a complete, web-based, content collaboration platform for small, medium and large companies and organizations everywhere, based on Microsoft Office SharePoint 2007 and the DITA open standard. DITA Exchange is developed by Content Technologies ApS of Denmark.
DITA Exchange is available as a web-based service, which means you can start developing collaborative and reusable technical documentation based on the DITA standard in days and weeks (rather than in months and years) with no software installation required at your site. More information will be available on my web site soon but please email me at DITA Exchange enquiries if you'd like to discuss how DITA Exchange can help you.
I will of course be continuing my work as an independent technical communications and information design consultant alongside my work with DITA Exchange.
DITA Exchange is available as a web-based service, which means you can start developing collaborative and reusable technical documentation based on the DITA standard in days and weeks (rather than in months and years) with no software installation required at your site. More information will be available on my web site soon but please email me at DITA Exchange enquiries if you'd like to discuss how DITA Exchange can help you.
I will of course be continuing my work as an independent technical communications and information design consultant alongside my work with DITA Exchange.
Wednesday, 4 June 2008
Update from Philadelphia (2)
Many more good things today at the STC Summit in Philadelphia. Ginny Redish gave a presentation on "Writing as an Asynchronous Conversation", in which she related Grice's maxims of conversation to the sort of technical writing many of us are involved in. In a conversation that is asynchronous - as opposed to a synchronous one - we need to anticipate the questions our unknown interlocutor may have, and prepare answers that are not merely accurate, but also appropriate in tone and context. No wonder good tech writing is so difficult to achieve! Ginny gave many examples (some from her book Letting Go of the Words) to show how approaching tech writing as a conversation produced engaging and effective results.
More to come from this great conference tomorrow.
More to come from this great conference tomorrow.
Tuesday, 3 June 2008
Update from Philadelphia
I'm at the STC Conference in Philadelphia this week and there are loads of good things hapening.
I went to a session on the STC's ongoing work on creating a "body of knowledge" for the technical communication profession. This is a descriptive, not a prescriptive, exercise and the aim is to build a comprehensive taxonomy of our profession. This will eventually become a web portal with links to relevant resources. Although this project is separate from any work on "technical writer certification" (a bit of a perennial argument in STC circles) it does have implications for education, and I will keep my academic colleagues at Sheffield Hallam University updated.
I'm also attending various practical eductaional sessions which I hope will make my own work easier.
Being at a conference like this, with lots of people I usually only meet on lists and networking sites is great fun, but there are plenty of serious things going on.
The opening keynote address was given by Howard Rheingold, the first editor of HotWired and the man who gave the world the term "virtual communities", As you might expect, he gave an entertaining and stimulating presentation.I went to a session on the STC's ongoing work on creating a "body of knowledge" for the technical communication profession. This is a descriptive, not a prescriptive, exercise and the aim is to build a comprehensive taxonomy of our profession. This will eventually become a web portal with links to relevant resources. Although this project is separate from any work on "technical writer certification" (a bit of a perennial argument in STC circles) it does have implications for education, and I will keep my academic colleagues at Sheffield Hallam University updated.
I'm also attending various practical eductaional sessions which I hope will make my own work easier.
Monday, 26 May 2008
Can better technical documentation give your business a competitive advantage?
Many businesses regard the need to produce user documentation for their products as an unfortunate and expensive necessity, and they are therefore ready to classify their tech docs department as a "cost centre", rather than a "revenue centre". When times get tough, workers in "cost centres" are the first to feel the squeeze.
As someone who as spent the last 15 years of my professional career producing user documentation I am bound to see this attitude as wrong. Good technical documentation which focuses on user tasks helps people get their work done using the products you sell. People who are happy using the products you sell are more likely to renew their support license next year, or to upgrade to your next release, or to specify your products for their next expansion. They are less likely to clog up your customer support lines with trivial questions about your products. These are definite financial benefits to your business, but they are difficult to quantify.
Luckily there is a contrasting attitude that is beginning to gain popularity. In this approach, all types of information within a business organisation are regarded as business assets, that need to addressed, managed, and exploited. A recent blog on The Content Wrangler web site, written by Jake Sorofman of JustSystems takes this idea one step further. In Thinking Outside the (Tech Docs) Box: Structured Authoring as Competitive Advantage Sorofman emphasises the advantages of adopting an information management policy based on a system of structured authoring. He places technical documents - the user guides and help systems used regularly by customers - at the centre of the corporation-customer relationship, and calls such documents "value generators" as they help build trust and confidence. Structured authoring, which allows content re-use to create multiple and flexible (and in some cases, on demand) information products from the same sources, means that writers can become more efficient. One of the most interesting systems for structured authoring is the Darwin Information Typing Architecture or DITA, which is an XML specialisation managed by OASIS.
Sorofman makes a convincing case for technical writers and their work to be recognised for their significant role not only in providing user documentation but in building the customer relationship, and of course, I think he's quite right.
I hope to be offering more comments on DITA in this blog in the next few weeks.
As someone who as spent the last 15 years of my professional career producing user documentation I am bound to see this attitude as wrong. Good technical documentation which focuses on user tasks helps people get their work done using the products you sell. People who are happy using the products you sell are more likely to renew their support license next year, or to upgrade to your next release, or to specify your products for their next expansion. They are less likely to clog up your customer support lines with trivial questions about your products. These are definite financial benefits to your business, but they are difficult to quantify.
Luckily there is a contrasting attitude that is beginning to gain popularity. In this approach, all types of information within a business organisation are regarded as business assets, that need to addressed, managed, and exploited. A recent blog on The Content Wrangler web site, written by Jake Sorofman of JustSystems takes this idea one step further. In Thinking Outside the (Tech Docs) Box: Structured Authoring as Competitive Advantage Sorofman emphasises the advantages of adopting an information management policy based on a system of structured authoring. He places technical documents - the user guides and help systems used regularly by customers - at the centre of the corporation-customer relationship, and calls such documents "value generators" as they help build trust and confidence. Structured authoring, which allows content re-use to create multiple and flexible (and in some cases, on demand) information products from the same sources, means that writers can become more efficient. One of the most interesting systems for structured authoring is the Darwin Information Typing Architecture or DITA, which is an XML specialisation managed by OASIS.
Sorofman makes a convincing case for technical writers and their work to be recognised for their significant role not only in providing user documentation but in building the customer relationship, and of course, I think he's quite right.
I hope to be offering more comments on DITA in this blog in the next few weeks.
Friday, 23 May 2008
One of cyber-life's little ironies
Today I received an email from an online publication I subscribe to inviting me to follow a link to register for a seminar. When I clicked the link, my browser warned me that the page was requesting "enhanced abilities" that were "UNSAFE" (their caps, not mine).
You'll never guess what the topic of the seminar was - "Delivering technology to protect and secure your information".
You'll never guess what the topic of the seminar was - "Delivering technology to protect and secure your information".
Tuesday, 6 May 2008
XML in the service of crime
How's that for a headline? I hope it's caught your interest. Strictly speaking, the headline should be "XML in the service of reporting crime", or better still, "XML in the service of making historical accounts of crime available and searchable online", but that doesn't have the same ring to it!
So what on earth am I talking about? Well, two hundred and thirty-nine years worth of reports of proceedings at London's Central Criminal Court, familiarly known as the Old Bailey, have just been made available online in a relaunch of the Old Bailey Online web site.
The "Proceedings", covering the period from 1674 to 1913, started off as privately published journalism and gradually developed into quasi official records. They were discontinued quite abruptly when the law was changed to make it obligatory to have an official court reporter make a verbatim record of every trial.
According to Professor Richard Shoemaker of Sheffield University, the records are a "treasure trove of social, legal and family history....Now everyone from schoolchildren and amateur historians to scholars working in a range of academic disciplines can have easy access to this wealth of information."
I find historical documents like these quite fascinating, particularly when they refer to my home town. I am a very loyal Londoner, and I know the City quite well. I am also a bit of an amateur genealogist and I was eager to search the records to see if any of my forbears were ever "transported for life" or worse. Searching through the records is what brings us neatly back to XML.
The Old Bailey Online site includes considerable information about the project itself, including details of how the original documents were digitised, and how the texts were then marked up using XML tags so that information could be categorised. I am very pleased that this information has been included. Many people are quite dismissive of markup languages, and believe that the availability of full text-search has made markup obsolete. This project makes a fascinating example of why structured markup is useful and important.
So what on earth am I talking about? Well, two hundred and thirty-nine years worth of reports of proceedings at London's Central Criminal Court, familiarly known as the Old Bailey, have just been made available online in a relaunch of the Old Bailey Online web site.
The "Proceedings", covering the period from 1674 to 1913, started off as privately published journalism and gradually developed into quasi official records. They were discontinued quite abruptly when the law was changed to make it obligatory to have an official court reporter make a verbatim record of every trial.
According to Professor Richard Shoemaker of Sheffield University, the records are a "treasure trove of social, legal and family history....Now everyone from schoolchildren and amateur historians to scholars working in a range of academic disciplines can have easy access to this wealth of information."
I find historical documents like these quite fascinating, particularly when they refer to my home town. I am a very loyal Londoner, and I know the City quite well. I am also a bit of an amateur genealogist and I was eager to search the records to see if any of my forbears were ever "transported for life" or worse. Searching through the records is what brings us neatly back to XML.
The Old Bailey Online site includes considerable information about the project itself, including details of how the original documents were digitised, and how the texts were then marked up using XML tags so that information could be categorised. I am very pleased that this information has been included. Many people are quite dismissive of markup languages, and believe that the availability of full text-search has made markup obsolete. This project makes a fascinating example of why structured markup is useful and important.
Sunday, 27 April 2008
Where's that command gone?
I have been using Microsoft Word professionally for quite a long time - since Word 2 on Windows 3, if you want to get historical about it. Each time Microsoft have presented a major upgrade I've got a little annoyed - sometimes more than a little - because they keep moving the commands. Just when you get used to finding something on particular menu, they go right ahead and bring out a new version, and - where's that command gone again?
Microsoft Office 2007 brought in a huge redesign of the user interface, and there's been a lot of criticism because of it. People just don't like change. Worse still, from Microsoft's point of view, is that organisations and individuals have been slow to upgrade to this new version, because it looks and feels so different from its predecessors. I myself am still sitting on the fence, with Office 2003 on my desktop machine where I do most of my work, and Office 2007 on my laptop.
There is a lot of help available if you want to (or have to) make the transition from Office 2003 to Office 2007 - much of it on the Microsoft Office Online web site. One item that's particularly useful for Word users is an interactive tool that maps Word 2003 commands to their Word 2007 equivalents. (While you wait for it to load you might like to reflect on the irony that this tool has been built with Adobe Flash.)
I'm trying to share my knowledge and expertise as widely as I can, and because of this I've recently started a Microsoft Word Users Club on Ecademy, which is a social networking website for business and self-employed people. Ecademy is more than just an online network as there are regular real-life Ecademy meetings all over Britain and in many other countries as well. This new Ecademy group isn't in competition with the existing Word user lists and forums, it's just an extra way of spreading some useful information.
Microsoft Office 2007 brought in a huge redesign of the user interface, and there's been a lot of criticism because of it. People just don't like change. Worse still, from Microsoft's point of view, is that organisations and individuals have been slow to upgrade to this new version, because it looks and feels so different from its predecessors. I myself am still sitting on the fence, with Office 2003 on my desktop machine where I do most of my work, and Office 2007 on my laptop.
There is a lot of help available if you want to (or have to) make the transition from Office 2003 to Office 2007 - much of it on the Microsoft Office Online web site. One item that's particularly useful for Word users is an interactive tool that maps Word 2003 commands to their Word 2007 equivalents. (While you wait for it to load you might like to reflect on the irony that this tool has been built with Adobe Flash.)
I'm trying to share my knowledge and expertise as widely as I can, and because of this I've recently started a Microsoft Word Users Club on Ecademy, which is a social networking website for business and self-employed people. Ecademy is more than just an online network as there are regular real-life Ecademy meetings all over Britain and in many other countries as well. This new Ecademy group isn't in competition with the existing Word user lists and forums, it's just an extra way of spreading some useful information.
Friday, 25 April 2008
At last, some consideration for users
As I work extensively with companies developing computer software and hardware, I am proud to be a member of the British Computer Society (the BCS). I receive regular emails and magazines and occasionally attend local meetings. This week an email newsletter alerted me to a blog by John Morris on the BCS web site entitled "Data Migration and User Stories".
Morris writes in praise of "User Stories" used in Agile programming which are (and here he quotes from Wikipedia) "A software system requirement formulated as one or two sentences in the everyday language of the user". When I read this I didn't know whether to cheer or to weep. Here is a technical expert in a highly technical field who is at last paying attention to the fact that the system he is building needs to be used by real-world end users - not techies or geeks - to do real-world jobs. I suppose any consideration of user needs is a huge improvement on no consideration at all, so I think I'll err on the side of cheering.
But putting the needs of the real end user at the focus of technology projects is something everyone should all aspire to, and technical authors, usability specialists, and interface designers have been fighting on behalf of real end users for decades. It's been a fight because in most cases software developers and other technical experts dismiss our concerns because we're not programmers. The only things that are new about Agile "User Stories" is that a it's a cute name for thinking about real end users, and it's part of a popular development methodology which happens to be the latest trend.
I've not been a big fan of Agile, because in most of the implementations I've seen the daily scrums and the like focus on minutiae of code, and the big picture goals - helping real-world end users do their jobs - get lost. But if Agile development teams really do develop user stories, and really do keep referring back to them to make sure their project is on track, then there is a glimmer of hope.
Morris writes in praise of "User Stories" used in Agile programming which are (and here he quotes from Wikipedia) "A software system requirement formulated as one or two sentences in the everyday language of the user". When I read this I didn't know whether to cheer or to weep. Here is a technical expert in a highly technical field who is at last paying attention to the fact that the system he is building needs to be used by real-world end users - not techies or geeks - to do real-world jobs. I suppose any consideration of user needs is a huge improvement on no consideration at all, so I think I'll err on the side of cheering.
But putting the needs of the real end user at the focus of technology projects is something everyone should all aspire to, and technical authors, usability specialists, and interface designers have been fighting on behalf of real end users for decades. It's been a fight because in most cases software developers and other technical experts dismiss our concerns because we're not programmers. The only things that are new about Agile "User Stories" is that a it's a cute name for thinking about real end users, and it's part of a popular development methodology which happens to be the latest trend.
I've not been a big fan of Agile, because in most of the implementations I've seen the daily scrums and the like focus on minutiae of code, and the big picture goals - helping real-world end users do their jobs - get lost. But if Agile development teams really do develop user stories, and really do keep referring back to them to make sure their project is on track, then there is a glimmer of hope.
Saturday, 19 April 2008
Death of a muse
I don't usually write about poetry, but I can't resist the opportunity to comment on a news item I heard this week. While there are arguments about the literary merits of John Betjeman's poetry, and about the new statue of him at St. Pancras station, I have always found his work readable and amusing, even if not profound or deeply meaningful. There is a certain kind of Englishness, at once both deferential and self-denigrating, that was exemplified by his poetry. He managed to show his love for England even while he was satirising it, and a particularly good example of this is shown in one of my favourite Betjeman poems, A Subaltern's Love Song, published in 1941.
The era this poem evokes was familiar to me in my childhood, not at first-hand (I'm not that old) but at second-hand. My mother and her sisters were, like this poem's heroine, young women in the Second World War, although their origins were closer to the urban working class than to the golf clubs and tennis courts of Surrey. But they loved this poem, the world it portrayed, and the way Betjeman could praise and mock in a single phrase.
I was therefore quite sad to learn that the woman who was Betjeman's muse for this poem and who really was called Miss Joan Hunter Dunn, passed away earlier this month at the age of 92. She has received an extensive and informative obituary in the Times, and has been the subject of comment in The Guardian and elsewhere. My mother and her sisters would have felt she deserved nothing less.
The era this poem evokes was familiar to me in my childhood, not at first-hand (I'm not that old) but at second-hand. My mother and her sisters were, like this poem's heroine, young women in the Second World War, although their origins were closer to the urban working class than to the golf clubs and tennis courts of Surrey. But they loved this poem, the world it portrayed, and the way Betjeman could praise and mock in a single phrase.
I was therefore quite sad to learn that the woman who was Betjeman's muse for this poem and who really was called Miss Joan Hunter Dunn, passed away earlier this month at the age of 92. She has received an extensive and informative obituary in the Times, and has been the subject of comment in The Guardian and elsewhere. My mother and her sisters would have felt she deserved nothing less.
Saturday, 15 March 2008
Reading by numbers
I am indebted to Karen Schriver, author of Dynamics in Document Design, for posting a note to the Info-Design Cafe mailing list about a recent article in the Wall Street Journal about readability formulas.
In his article "Can you read as well as a fifth-grader? Check the formula" columnist Carl Bialik discusses the readability formulas included in word processing software such as Microsoft Word, and discusses the value of the mechanical application of such formulas. He has opinions from both supporters and detractors of readability formulas, and counts both Karen Schriver, and Professor J. Peter Kincaid, one of the original instigators of the Flesch-Kincaid formula used in Microsoft Word, amongst those who question the value of the formulas.
I recently read a far more sustained attack on readability formulas, and in particular on their "dubious use" by the UK's Department for Education and Skills (DfES), written by Martin Cutts of the Plain Language Commission. In Writing by numbers: are readability formulas to clarity what karaoke is to song? Cutts complains that public bodies like the DfES use readability formulas as part of their propaganda and ignore the obvious shortcomings of what he terms "crude" tests. He notes that the main problem with readability tests is that:
In an effort to offer an alternative to the flawed readability formulas, Cutts and the Plain Language Commission have published a Plain English Lexicon, available free of charge for download from their website. The lexicon helps you find out whether the words you write will be easily understood, by comparing their grade level in the US Living Word Vocabulary (LWV) and their frequency in the UK British National Corpus (BNC). Words that have low LWV grade levels and high BNC frequencies should be easily understood by readers on both side of the Atlantic, according to Cutts. As long as the spelling isn't too different over there.
In his article "Can you read as well as a fifth-grader? Check the formula" columnist Carl Bialik discusses the readability formulas included in word processing software such as Microsoft Word, and discusses the value of the mechanical application of such formulas. He has opinions from both supporters and detractors of readability formulas, and counts both Karen Schriver, and Professor J. Peter Kincaid, one of the original instigators of the Flesch-Kincaid formula used in Microsoft Word, amongst those who question the value of the formulas.
I recently read a far more sustained attack on readability formulas, and in particular on their "dubious use" by the UK's Department for Education and Skills (DfES), written by Martin Cutts of the Plain Language Commission. In Writing by numbers: are readability formulas to clarity what karaoke is to song? Cutts complains that public bodies like the DfES use readability formulas as part of their propaganda and ignore the obvious shortcomings of what he terms "crude" tests. He notes that the main problem with readability tests is that:
[those] who apply them uncritically tend to assume that any 10-sentence [passage] with, say, 12 polysyllabic words is as good and clear as any other with 12 polysyllabic words. But its grammar and punctuation may be poor and its message muddled, ambiguous or misleading. Such findings are only likely to emerge after usability testing (not readability testing) or editorial scrutiny or both.
In an effort to offer an alternative to the flawed readability formulas, Cutts and the Plain Language Commission have published a Plain English Lexicon, available free of charge for download from their website. The lexicon helps you find out whether the words you write will be easily understood, by comparing their grade level in the US Living Word Vocabulary (LWV) and their frequency in the UK British National Corpus (BNC). Words that have low LWV grade levels and high BNC frequencies should be easily understood by readers on both side of the Atlantic, according to Cutts. As long as the spelling isn't too different over there.
Wednesday, 12 March 2008
On wranglers, and other fancy titles
What's in a name? More particularly, what's in the name of a profession? Some professions are easy to identify by a one word name: tinker, tailor, soldier, spy. Other professional designations are longer: civil engineer, cloakroom attendant, sagger-maker's bottom-knocker, or Lord Privy Seal. (Job titles can get silly - Lois Wakeman has collected some from her local supermarket such as "Oven Fresh Manager", and I have spotted nice ones in Social Services departments like "Teenage Pregnancy Team Leader".)
For my particular professional activity there is no single agreed term. I like to call myself an Information Design Consultant, because what I can do goes far beyond just writing the right words. But I have been called a technical writer, a technical communicator, an information developer, a technical author, a documentation specialist, or more fancifully, a font fondler and a member of the word police (and of the Word police as well). Scott Abel goes by another term - he calls himself the Content Wrangler.
At the University of Cambridge a wrangler is a student who gets first class honours in mathematics; it's also the name of a brand of jeans; and in the US in particular it's someone who handles animals, particularly cattle and horses, professionally. I think it's this meaning Scott had in mind - a content wrangler herds words and content elements together, selecting the best ones and coralling them into the places they need to be. Not an easy job, but immensely satisfying if done well. Scott is a content management specialist, a conference organiser, and a first class speaker himself, and his Content Wrangler web site and newsletter are extremely popular amongst us technical writers/authors/communicators.
Less than two weeks ago Scott launched a social networking website for anyone interested in "content wrangling" called The Content Wrangler Community, and yes, it is one of the groups on Ning that I was invited to join last week.
According to Scott:
For my particular professional activity there is no single agreed term. I like to call myself an Information Design Consultant, because what I can do goes far beyond just writing the right words. But I have been called a technical writer, a technical communicator, an information developer, a technical author, a documentation specialist, or more fancifully, a font fondler and a member of the word police (and of the Word police as well). Scott Abel goes by another term - he calls himself the Content Wrangler.
At the University of Cambridge a wrangler is a student who gets first class honours in mathematics; it's also the name of a brand of jeans; and in the US in particular it's someone who handles animals, particularly cattle and horses, professionally. I think it's this meaning Scott had in mind - a content wrangler herds words and content elements together, selecting the best ones and coralling them into the places they need to be. Not an easy job, but immensely satisfying if done well. Scott is a content management specialist, a conference organiser, and a first class speaker himself, and his Content Wrangler web site and newsletter are extremely popular amongst us technical writers/authors/communicators.
Less than two weeks ago Scott launched a social networking website for anyone interested in "content wrangling" called The Content Wrangler Community, and yes, it is one of the groups on Ning that I was invited to join last week.
According to Scott:
The Content Wrangler Community is the new social network dedicated to people who value content as a business asset, worthy of being effectively managed. This is the place where technical communicators, medical and science writers, marketing pros, content management gurus, indexers, online community managers, document engineers, information architects, localization and translation pros, e-learning pros, taxonomists, bloggers, documentation and training managers, and content creators of all types hang out. It's much more than a blog. It's a place to join peers, to share, to collaborate, to contribute, to find information.
"Social networks are about connecting people and ideas," said Scott Abel, manager of The Content Wrangler Community. "Web-based social networks are the natural evolution of the web from a passive broadcast medium to a multi-directional communication platform that more closely supports the way humans interact in the physical world. We congregate. We join others like us. We interact with birds of a feather. Until the advent of social networking tools, the web failed miserably to connect people in meaningful ways."I think this community is a great idea, and so do about 680 others, at the last count. I certainly need all the help I can get when I am "wrangling" words and pictures and information content into the right size and shape and format for my clients' needs, and I am sure I'll get a lot of inspiration here.
Wednesday, 5 March 2008
Do-it-yourself social networking
In the last week I have had two different invitations to join two completely unrelated social networks, but both are hosted on the same service - Ning. Ning offers ordinary mortals - people who wouldn't know where to start if they were told to configure their own webserver - a chance to create their own social networks.
This sounds like a great idea. People can start their own networks for their own interests - vintage cars, stamp-collecting, train-spotting - or their own business needs - customers, distributors or suppliers.
Ning is a clear example of a "Web 2.0" phenomenon - distributed control, open access, and user-generated content. (I am actually a sceptic about whether there is anything new in "Web 2.0". It could just be all marketing hype.) But there are two big dangers inherent in all this. The first is related to quality. The content you are reading might not actually be of any value, and might easily be bogus or deliberately misleading. How can you verify the credentials of the person whose page you are reading? In a commercial environment, a successful Wiki has participants from all levels of the company, not just the geeks. Knowing that the CEO is reading what you write can help keep you on track. And in non-commercial environments, you need to achieve a high level of participation for a user-generated knowledge network to be self-regulating.
The second problem is quantity. I barely have time to read my email, and once I start looking at the networking sites I can lose hours of productive time without noticing it. There aren't enough hours in the day to keep track of everything, which means I constantly need to make decisions about what messages to open, what links to follow and what articles to read. Sometimes, it feels easier just to switch off.
This sounds like a great idea. People can start their own networks for their own interests - vintage cars, stamp-collecting, train-spotting - or their own business needs - customers, distributors or suppliers.
Ning is a clear example of a "Web 2.0" phenomenon - distributed control, open access, and user-generated content. (I am actually a sceptic about whether there is anything new in "Web 2.0". It could just be all marketing hype.) But there are two big dangers inherent in all this. The first is related to quality. The content you are reading might not actually be of any value, and might easily be bogus or deliberately misleading. How can you verify the credentials of the person whose page you are reading? In a commercial environment, a successful Wiki has participants from all levels of the company, not just the geeks. Knowing that the CEO is reading what you write can help keep you on track. And in non-commercial environments, you need to achieve a high level of participation for a user-generated knowledge network to be self-regulating.
The second problem is quantity. I barely have time to read my email, and once I start looking at the networking sites I can lose hours of productive time without noticing it. There aren't enough hours in the day to keep track of everything, which means I constantly need to make decisions about what messages to open, what links to follow and what articles to read. Sometimes, it feels easier just to switch off.
Monday, 3 March 2008
Content management at STC UK
This weekend I took part in a one-day conference on Content Management that was held by the STC UK Chapter. I gave a presentation on my personal experience of introducing a document management system in one department of a large IT division of a leading UK company where I was working as a contractor.
I was able to report that the document management solution we chose, Alfresco, was a great success both technically, in terms of its features and ease of use, and practically, in terms of user acceptance and improved working practices. Where the project came a little unstuck was in what, for want of a better word, I'd call the "political" sphere. The project lacked a business sponsor at a sufficiently senior level in the company hierarchy, so by the time I left the company involved it was unclear whether a budget would be available to make the solution I'd introduced a permanent feature of the department's infrastructure.
Update 5th March 2008: I've just heard that the company have at last decided to go ahead with an official implementation of Alfresco. Perhaps it was something I said?
I was able to report that the document management solution we chose, Alfresco, was a great success both technically, in terms of its features and ease of use, and practically, in terms of user acceptance and improved working practices. Where the project came a little unstuck was in what, for want of a better word, I'd call the "political" sphere. The project lacked a business sponsor at a sufficiently senior level in the company hierarchy, so by the time I left the company involved it was unclear whether a budget would be available to make the solution I'd introduced a permanent feature of the department's infrastructure.
Update 5th March 2008: I've just heard that the company have at last decided to go ahead with an official implementation of Alfresco. Perhaps it was something I said?
Friday, 22 February 2008
Headline news for punctuation
Punctuation has been making headlines in New York, it appears. Yesterday's Guardian carried a leader article "In praise of ... the semicolon", citing the semicolon's reappearance in New York subway signs, and the subsequent praise from the New York Times. The Guardian, a newspaper famously pilloried for its frequent typos in days gone by, takes issue with the NYT over whether the semicolon had fallen into disuse. While the NYT wrote that many considered it a "pretentious anachronism", the Guardian writes that in its pages it has been kept in regular and correct use. A debate has ensued on the Guardian web site, which is itself great news for those of us who appreciate the nuances of our language.
Monday, 11 February 2008
Apostrophe overload
I am currently revising some user-facing documentation for a new client. The existing documents were prepared by a member of staff, no longer working for the company concerned, who had never had any training in technical writing skills. There's a series of about a dozen Word documents of about 20 pages each. All the formatting has been done without the use of styles, additional white space has been added with empty paragraphs, and all the graphics are floating. Even the Table of Contents has been created manually. These are all examples of inefficient ways to use Microsoft Word, and they are typical of work produced by people who are, in terms of their documentation skills, well-meaning amateurs. (They may well excel in their own professional fields, and they are probably really nice people too!)
I can deal with all these things, and if I am asked to, I can show people how to save time and energy by doing things in different ways that allow for consistency and repeatability across document sets.
The thing that has really upset me with these particular documents is the poor quality of the writing itself. The most grating offence against accepted current usage that this writer is guilty of is the use of an apostrophe to indicate the plural of nouns. I've seen "operator's", "user's", "extra's", and "area's" - not one of them indicating a possessive - in just a few pages. Poor Lynne Truss would be having a fit by now, and to tell you the truth, I am nearly there myself.
I can deal with all these things, and if I am asked to, I can show people how to save time and energy by doing things in different ways that allow for consistency and repeatability across document sets.
The thing that has really upset me with these particular documents is the poor quality of the writing itself. The most grating offence against accepted current usage that this writer is guilty of is the use of an apostrophe to indicate the plural of nouns. I've seen "operator's", "user's", "extra's", and "area's" - not one of them indicating a possessive - in just a few pages. Poor Lynne Truss would be having a fit by now, and to tell you the truth, I am nearly there myself.
Wednesday, 6 February 2008
Talking about document management
I have been invited to take part in a one day event about content management being held by the UK Chapter of the STC on 1st March 2008. I will be talking about some of the practical aspects of trying to introduce a document management system in a large IT department.
If like me you'd spent nearly 15 years creating and working with documents for internal and external audiences in a range of hi-tech environments, you might have expected that the fundamentals of document management were universally understood and supported, in theory at least if not always in practice. In the "unofficial case study" I am presenting at this STC meeting I will explain why what was obvious to me wasn't obvious to those around me, why I was asked to do something about it, what I tried to achieve, and how far I actually got.
Other speakers at this meeting will be talking about different aspects of content management, and I am sure it will be a worthwhile day. I do hope you will be able to join us.
By the way, I am also going to be giving two small presentations at the STC Technical Communications Summit in Philadelphia in June this year, where I will also be organising activities for members of the STC's Europe Special Interest Group. If I don't get to see you in March, maybe we'll meet up in June?
If like me you'd spent nearly 15 years creating and working with documents for internal and external audiences in a range of hi-tech environments, you might have expected that the fundamentals of document management were universally understood and supported, in theory at least if not always in practice. In the "unofficial case study" I am presenting at this STC meeting I will explain why what was obvious to me wasn't obvious to those around me, why I was asked to do something about it, what I tried to achieve, and how far I actually got.
Other speakers at this meeting will be talking about different aspects of content management, and I am sure it will be a worthwhile day. I do hope you will be able to join us.
By the way, I am also going to be giving two small presentations at the STC Technical Communications Summit in Philadelphia in June this year, where I will also be organising activities for members of the STC's Europe Special Interest Group. If I don't get to see you in March, maybe we'll meet up in June?
Tuesday, 5 February 2008
Keeping up with Word
I want to thank Ellis Pratt of Cherryleaf for reminding me about the Microsoft Word Team blog, which contains regular updates of tips and tricks for the latest version of Microsoft Word.
My business, Dannywell Ltd., is a Microsoft Registered Partner and I often use Microsoft Word and other Microsoft products to produce documentation for my clients. Many clients express a preference for documentation in Word as they feel that it will be easier for their own staff to maintain in the long run. Luckily for me, of course, some of these clients decide that after all their own staff aren't documentation specialists, and they invite me back to update their user documentation when they release upgrades to their products.
In my experience, very few organisations have migrated to Microsoft Office 2007, and so I need to keep up with two versions of Word simultaneously (the Office 2003, and Office 2007 versions). Resources such as the Microsoft Word Team blog are very valuable tools that help me do this.
My business, Dannywell Ltd., is a Microsoft Registered Partner and I often use Microsoft Word and other Microsoft products to produce documentation for my clients. Many clients express a preference for documentation in Word as they feel that it will be easier for their own staff to maintain in the long run. Luckily for me, of course, some of these clients decide that after all their own staff aren't documentation specialists, and they invite me back to update their user documentation when they release upgrades to their products.
In my experience, very few organisations have migrated to Microsoft Office 2007, and so I need to keep up with two versions of Word simultaneously (the Office 2003, and Office 2007 versions). Resources such as the Microsoft Word Team blog are very valuable tools that help me do this.
Monday, 4 February 2008
Save Pervez
The Independent newspaper has launched a campaign to save the life of an Afghan student journalist, Sayed Pervez Kambaksh aged 23, who has been sentenced to death for downloading a human rights report from the Internet critical of the lack of rights for women in Afghanistan. Kambaksh was tried before a religious court for "disrespecting the Koran", and was not allowed any legal defence.
Executing people for just reading about human rights is a new low, even from a regime not noted for its open and liberal attitudes. It is, says the Independent, an "affront to civilized values".
I urge you to read the article in the Independent and to sign the petition.
Executing people for just reading about human rights is a new low, even from a regime not noted for its open and liberal attitudes. It is, says the Independent, an "affront to civilized values".
I urge you to read the article in the Independent and to sign the petition.
Friday, 18 January 2008
Why "correctness" matters
Native speakers of English - or any other language - seem to know how to use their own language, and what is correct in language use, even without formal study of the rules of grammar. People just seem to know "what sounds right". Many very wise people have written about this at length and I wouldn't dare try and compete with Noam Chomsky, Steven Pinker or David Crystal.
Sometimes, as languages grow and develop, confusing situations occur with different meanings or different rules for similar sounding words. While recognising that language changes, we try to pass on these more sophisticated usages as they are keys to subtle yet meaningful variations in our speech and writing. Those of us who love clarity and correctness (and I count myself amongst them) can be upset when distinctions are lost, and this week Chicago Tribune columnist Mary Schmich eloquently bewailed the apparent loss of one distinct variation in usage. The particular distinction that bothered Schmich was the difference between "lie down" and "lay down". This is a distinction that I understood automatically, but I had to go to Michael Swan for a formal explanation. "Lay" means to put down carefully, says Swan, and takes an object. It has a regular form, but an awkward spelling in its past tense ("laid" not "layed"). "Lie", meaning to be or become horizontal, is an irregular verb, with the past tense "lay". It's easy to see how this may confuse some people.
The unhappiness that people like Schmich and I feel when distinctions are lost is not due to us being "old-fashioned", or "conservative", but because we believe that the variety that correct usage entails enriches language, while casual and thoughtless usage makes language poorer for all of us.
Sometimes, as languages grow and develop, confusing situations occur with different meanings or different rules for similar sounding words. While recognising that language changes, we try to pass on these more sophisticated usages as they are keys to subtle yet meaningful variations in our speech and writing. Those of us who love clarity and correctness (and I count myself amongst them) can be upset when distinctions are lost, and this week Chicago Tribune columnist Mary Schmich eloquently bewailed the apparent loss of one distinct variation in usage. The particular distinction that bothered Schmich was the difference between "lie down" and "lay down". This is a distinction that I understood automatically, but I had to go to Michael Swan for a formal explanation. "Lay" means to put down carefully, says Swan, and takes an object. It has a regular form, but an awkward spelling in its past tense ("laid" not "layed"). "Lie", meaning to be or become horizontal, is an irregular verb, with the past tense "lay". It's easy to see how this may confuse some people.
The unhappiness that people like Schmich and I feel when distinctions are lost is not due to us being "old-fashioned", or "conservative", but because we believe that the variety that correct usage entails enriches language, while casual and thoughtless usage makes language poorer for all of us.
Wednesday, 16 January 2008
Facebook under fire again
I'm a word lover, and a Facebook afficionado, so here's a story just made from me. Hasbro, the manufacturer of the word game Scrabble, has apparently told Facebook to stop hosting the Scrabulous application, and legal action may be forthcoming. Writing about this in his Techland blog on Fortune on CNN Money, Josh Quitter wonders why Hasbro have taken this approach.
He understands the need for companies to protect their intellectual property - Scrabble makes a lot of income for Hasbro - but surely banning Scrabulous would damage the Scrabble brand, which currently does not have an online version. Wouldn't a buy out or take-over make more sense?
Maybe Quitter is right, and the people running Hasbro haven't understood the dynamics of the online marketplace. Like some of the people in the music industry, they are so used to equating sales with moving physical products, that it's difficult for them to accommodate a new business paradigm.
"Paradigm", eh. That's a good word. Wonder what that would get me on a Triple Word Score?
He understands the need for companies to protect their intellectual property - Scrabble makes a lot of income for Hasbro - but surely banning Scrabulous would damage the Scrabble brand, which currently does not have an online version. Wouldn't a buy out or take-over make more sense?
Maybe Quitter is right, and the people running Hasbro haven't understood the dynamics of the online marketplace. Like some of the people in the music industry, they are so used to equating sales with moving physical products, that it's difficult for them to accommodate a new business paradigm.
"Paradigm", eh. That's a good word. Wonder what that would get me on a Triple Word Score?
Monday, 7 January 2008
Banished words, again
Many pundits and pedants enjoy listing the words they dislike, but Lake Superior State University surely deserves a special mention as they've been publishing their list every year since 1976. Back then they wanted to ban "meaningful", particularly "meaningful dialogue"and "meaningful input", which are just as meaningless today as they were more than thirty years ago.
I would happily support the banishment of some of the words and phrases on this year's list, such as "x is the new y" (for example, green is the new black), "surge" in relation to troop deployment rather than electricity supply, and "webinar" for a seminar delivered over the web. I'm not so sure about some of the others though. I am sometimes called a technical author, and I use some authoring tools particularly when I work on online help systems. Banning the verb "to author" might cause me a certain amount of difficulty (though admittedly, not very much). They would also outlaw "wordsmith", a rather whimsical and evocative description of some of the work I do.
I suppose I'll have to sit out a "perfect storm" of criticism now, which is what we have come to expect in this "post 9/11" world.
I would happily support the banishment of some of the words and phrases on this year's list, such as "x is the new y" (for example, green is the new black), "surge" in relation to troop deployment rather than electricity supply, and "webinar" for a seminar delivered over the web. I'm not so sure about some of the others though. I am sometimes called a technical author, and I use some authoring tools particularly when I work on online help systems. Banning the verb "to author" might cause me a certain amount of difficulty (though admittedly, not very much). They would also outlaw "wordsmith", a rather whimsical and evocative description of some of the work I do.
I suppose I'll have to sit out a "perfect storm" of criticism now, which is what we have come to expect in this "post 9/11" world.
Subscribe to:
Posts (Atom)
