Wednesday, 24 December 2008
User assistance "sans frontieres"
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.
Monday, 22 December 2008
I like predictions like these
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
Wednesday, 10 December 2008
Keeping up with contacts when the internet is "full"
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
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
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
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.
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?
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
"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"
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
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
Read the rest of this article on my web site...
Tuesday, 19 August 2008
Is editing a romantic profession?
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?
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
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
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
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
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
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"
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?
"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 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
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
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?
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
Wednesday, 18 June 2008
DITA Exchange discussed on an MSDN blog
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
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)
More to come from this great conference tomorrow.
Tuesday, 3 June 2008
Update from Philadelphia
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?
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
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
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?
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
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
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
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
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
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
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
Monday, 11 February 2008
Apostrophe overload
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
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
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
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
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
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
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.