Archive for the ‘Book recommendations’ Category

h1

Book review: Planning and Structuring User Assistance

August 6, 2013

Details:

************************

This was the second book I read from Marc Achtelig’s Technical Documentation Solutions Series. Like the first one I read (‘Designing‘), it was well-written in plain, simple language, and was laid out in such a way that I could dip in and out of it and use it as a reference book. While I read it from cover to cover for this review, I would expect that most readers would use it as a reference as each topic can stand alone.

Marc states that the intended audience for this series of books are:

  • full-time technical writers
  • developers, marketing professionals, and product managers who occasionally write some technical documentation
  • designers who create templates for user manuals and online help systems
  • multimedia experts who create screencasts, tutorials, and e-learning courses.

In my opinion, this Structuring book is mostly for technical writers or anyone else involved in writing product documentation (software or hardware).

The topics covered are:

  • General structuring principles
  • Choosing media
  • Planning documents
  • Planning document sections
  • Planning topics
  • Planning the order of sections and topics
  • Planning navigation.

As with the first book, in the author’s note in Chapter 1, Marc talks about the rules for designing templates and my first reaction was ‘Whose rules?’ Different organizations, industries, and countries can have different ‘rules’, so I was concerned that Marc was going to focus on a particular set of ‘rules’ that were familiar to him, but not necessarily apply to everyone else. However, he surprised me by his ability to make solid generic recommendations that crossed all sorts of boundaries and therefore that could apply to most situations.

In this book he starts straight in on what he calls the ‘universal principles’; specifically:

  • Don’t try to please everybody
  • Make it goal-centered (‘it’ being the document, topic, section etc.)
  • Layer information
  • Split complex information
  • Find the right amount of redundancy.

And further: ‘A user-friendly structure should reflect:

  • the tasks and goals of your primary user group
  • the information needs of your primary user group
  • the mental model of your primary user group’

I particularly liked the inclusion of ‘mental model’ in this list as I think it’s an aspect that often gets lost when we are defining who are users are.

And I LOVED this (p64-65):

What you shouldn’t include at all (in the preface):

  • Don’t congratulate users on choosing or buying your product. Most users don’t read manuals before using a product. They only read a manual when they have problems. Congratulating them in a situation like this may sound cynical and doesn’t add any information and value to your document. Phrases like this just stand in the way of the real information.
  • Don’t say that you’re pleased that users chose your product. Users don’t care about your feelings.

Note: It’s perfectly OK and important to build up a positive attitude toward your product. However, do so by providing value rather than words. Give users a reason to love your product and its documentation rather than telling them how wonderful both are.

Most of the notes I took as I was reading the first book also applied to this one, plus a few more specifically for this book:

  • Nice clear writing, with practical examples.
  • Excellent coverage of the basics and the do’s and don’ts. Good examples.
  • Excellent refresher for experienced practitioners; great advice for beginners.
  • Offers advice/rule and clear reasons for doing/not doing it.
  • All diagrams were clear and simple and got the message across successfully.
  • In this book he emphasizes the human touch required for indexing, and advises staying away from the automated indexes created by authoring tools; this is in direct contrast to what he said in the Designing book, and is a recommendation I agree with.
  • Unlike his Designing book, this one focuses more on online help.
  • Very comprehensive.

I only had a few negative comments about this book:

  • As with the first book, I read a PDF version of this book on an Android tablet (via Adobe Reader). There were some issues with odd artefacts in the PDF, e.g. single and double quote marks, en and em dashes all rendered as odd characters. This should have been checked/dealt with when the author verified the PDF output from their single-sourcing authoring tool as there were far too many for it to be an odd occurrence. UPDATE: The author sent me a couple of revised versions with different Adobe settings and one of those worked very well, with no artefacts displayed at all. He assured me that he had embedded the fonts and checked the display. If nothing else, this has shown that the same software on different platforms and different devices may render the text differently.

Overall, this is an excellent guide to planning and structuring electronic and printed product documentation. It is suitable for beginners and experienced practitioners alike.

I’ll leave the final word to Marc:

When deadlines are close and budgets are tight, it’s better to provide medium quality information but excellent navigation than to provide excellent information but poor navigation.

h1

Book review: Designing Templates and Formatting Documents

August 5, 2013

Details:

************************

This was the first book I read from Marc Achtelig’s Technical Documentation Solutions Series, and I look forward to reading others. Why? Because it was well-written in plain, simple language, and was laid out in such a way that I could dip in and out of it and use it as a reference book. While I read it from cover to cover for this review, I would expect that most readers would use it as a reference as each topic can stand alone.

Marc states that the intended audience for this series of books are:

  • full-time technical writers
  • developers, marketing professionals, and product managers who occasionally write some technical documentation
  • designers who create templates for user manuals and online help systems
  • multimedia experts who create screencasts, tutorials, and e-learning courses.

In my opinion, this Designing book is also for the person in a small company who has to set up templates for others to use; for example, an admin assistant. While the sections related to online help wouldn’t apply to them, those on page layout, etc. would.

The topics covered are:

  • Layout
  • Type area
  • Fonts /spacing
  • Screen layout
  • Page layout
  • Table design
  • Paragraph styles
  • Character styles

In the author’s note in Chapter 1, Marc talks about the rules for designing templates and my first reaction was ‘Whose rules?’ Different organizations, industries, and countries can have different ‘rules’, so I was concerned that Marc was going to focus on a particular set of ‘rules’ that were familiar to him, but not necessarily apply to everyone else. However, he surprised me by his ability to make solid generic recommendations that crossed all sorts of boundaries and therefore that could apply to most situations.

The other thing that surprised me was Marc’s ability to talk generically about authoring tools, yet not mention a single tool. But in no way did that detract from the information he provided — in fact, it enhanced it as he didn’t get caught up in what Word could do versus FrameMaker, versus RoboHelp, versus Flare, versus Author-it, versus any other authoring tool you might want to name.

Here are the notes I took as I was reading this book:

  • Nice clear writing, with practical examples.
  • Excellent coverage of the basics and the do’s and don’ts. Good examples.
  • Excellent refresher for experienced practitioners; great for beginners.
  • Offers advice/rule and clear reasons for doing/not doing it.
  • Lots of advice on setting up templates, without referring to ANY authoring tool — a remarkable achievement.
  • All diagrams were clear and simple and got the message across successfully.
  • While online help is dealt with, the book would be ideal for anyone setting up a document, not just technical communicators. Ideal also for those new to the profession.

I only had a few negative comments about this book:

  • While I found the advice to use keyboard shortcuts and meaningful names for paragraph and character styles useful, I found the style name examples he gave quite unconventional (in my experience) and against the author’s advice to use style names that were easy to interpret and remember.
  • I disagreed with his assertion that ‘most Help authoring tools create a well-designed index automatically’. This has NOT been my experience, and a competent author/indexer is needed for a useful index, otherwise it’s just a list of topics or words used, without any weight given to their importance or their contextual use.
  • I read a PDF version of this book on an Android tablet. There were some issues with odd artefacts in the PDF, e.g. single and double quote marks, en and em dashes all rendered as odd characters. This should have been checked/dealt with when the author verified the PDF output from their single-sourcing authoring tool as there were far too many for it to be an odd occurrence. Perhaps he didn’t follow his own advice on font selection and embedding… UPDATE: The author sent me a couple of revised versions with different Adobe settings and one of those worked very well, with no artefacts displayed at all. He assured me that he had embedded the fonts and checked the display. If nothing else, this has shown that the same software on different platforms and different devices may render the text differently.

Overall, this is an excellent guide to designing electronic and printed document templates, suitable for beginners and experienced practitioners alike.

h1

Book recommendation: Just my type

November 26, 2012

I haven’t done a book recommendation for ages, probably because I’ve been reading quite a lot of fiction recently and listening to general non-fiction audio books (such as those by Malcolm Gladwell) on my daily 40-minute walk.

However, a good friend recommended Just my type (by Simon Garfield) to me and I’m so glad he did.

What a terrific read! The subject matter (fonts and typefaces) sounds very dry and boring, but this book is any but. It is a delightful romp through typeface history from Gutenberg to just a year or so ago, and offers insights into some of the very human emotions associated with people who are passionate about their profession/vocation.

Garfield writes in such an engaging and entertaining manner that you don’t need to know much at all about fonts to learn something from his book. He covers fonts from Arial to Zipf and many fonts in between, particularly those we see on our computers every day.

I particularly loved Chapter 11 (DIY) where he gave a brief overview of the days of letter stamps, Letraset, IBM golf ball typewriters, Dymo label makers etc. — almost all of which I used in the 70s and 80s and even into the early 90s before I got my first computer.

This book stays with you — since reading it, I’ve really been noticing the types of fonts used for TV/movie credits, on signs, in advertising, logos, etc.

A great read that I highly recommend.

h1

Learning Author-it

May 3, 2011

My good friend and fellow Author-it Certified Consultant, Char James-Tanny, has her new book at the publishers. It will be ready for release and sale at the STC Summit in Sacramento, California in mid-May, 2011.

Her book is called ‘Learning Author-it‘ and it’s a very practical and useful introduction to the fundamentals of this complex, featured-filled and amazing software. How do I know this? Because I had the privilege of editing it!

Front cover of Learning Author-it book

Char and I have collaborated before on Author-it stuff, such as joint conference presentations and introductory training materials, and I’ve previously edited her other Author-it training materials, so I was honored to be asked to edit her book too. An even greater honor was to be asked to write the Foreword.

To round it out, our good friend Sue Heim did the indexing. Those of you who attend the same conferences that we do, know that we all hang out together, so it was great to work together too.

The time zone thing also worked well. Char would send me a revised version at the end of her work day (often midnight or later), which I’d receive during my day. As most of the editing was done over the Easter break, I’d work on it during my day, then send her my edits, which would be waiting in her Inbox when she woke up. So there was hardly any down time when one of us was waiting for the other.

If you use Author-it, or are planning to use Author-it, read this book. Not only are there heaps of step-by-step instructions, Char also goes into the reasons why you do — or don’t do — something in Author-it.

The book is available for pre-order from XMLPress (the publishers): http://xmlpress.net/publications/learning-author-it/. It will also be available at the STC Summit (where Char might even sign your copy for you!), from Barnes & Noble (pre-release), and from Amazon.com after it’s been released.

[Links last checked May 2011]

h1

Book review: The Compass

April 5, 2010

Sarah O’Keefe and her team at Scriptorium have pulled together a collection of their free white papers into a book titled The Compass: Essential Reading about XML, DITA, and Web 2.0.

I picked up a copy at the 2010 WritersUA Conference (thanks Sarah!), and even though the subject matter didn’t interest me greatly (I’m not on the DITA bandwagon), I read this book from cover to cover in two short sessions. And I learned a lot.

So many of those on the DITA bandwagon are true evangelists, but not Sarah and her colleagues. They live and breathe structured authoring, DITA, XML and other technologies, but they are very realistic about the benefits and downsides of these technologies for both companies and implementation teams — and the technical writers whose work will be affected on a daily basis.

The first three chapters (Structured authoring and XML, Managing implementation of structured authoring, and Assessing DITA as a foundation for XML implementation) are a great overview of the technologies available. Each chapter is easy to read and explains how these technologies can help organizations and technical writing teams. And how they are not for everyone or every organization.

The next four chapters contain specific (and helpful) information on how to install and use the various technologies. They document the ‘gotchas’ and the hacks you have to do to get them to work — hacks that aren’t necessarily part of the source documentation. For anyone implementing DITA Open Toolkit, these hacks alone are worth the price of the book! Then there are instructions for configuring fonts in FOP and DITA OT, and removing white space in structured FrameMaker documents.

The final chapter deals a little with Web 2.0 in technical documentation, and has a really useful list of ways you can evaluate credibility in public forums and user-generated content.

[Links last checked March 2010]

h1

Book review: The Global English Style Guide

October 19, 2009

The subtitle of John R. Kohl’s The Global English Style Guide is Writing Clear, Translatable Documentation for a Global Market — and that says it all, really.

This book is a fabulous resource for any technical writer, whether your writing is likely to be translated into another language or not. There are plenty of readers of our documentation whose first language is not English, and others who have difficulties with the nuances of the English language. Just like good design for accessibility is good design for all, technical communicators who follow the writing recommendations in this book should end up with technical documentation that’s clearer for everyone.

In addition, clear writing should save money in translation costs by reducing the ‘to-ing and fro-ing’ of the “What do you mean here?” questions by the translation agency.

Kohl provides hundreds of practical examples in his 300 page book. These examples are aimed directly at technical writers — particularly those who write software documentation.

Everything is set out clearly, with a comprehensive table of contents, a glossary, a bibliography of further resources, and an index. And it’s peppered with notes and hints and tips.

I read this book over a few nights (yes, that’s sad — reading a style guide for pleasure!), and highly recommend it for any technical writer’s arsenal of style guides.

You can purchase this book via the CyberText bookstore (affiliated with Amazon.com): http://astore.amazon.com/cybertconsul-20/detail/1599946572

h1

Australian book prices

August 28, 2009

For some years now it has been cheaper for Australians to buy specialist books from Amazon and other online stores based in the US, than to purchase them from Australian booksellers (bricks and mortar or online). Even adding in the shipping costs from the US to Australia (there’s no free shipping to Australia from Amazon — the free shipping option is only available to US addresses), it’s STILL cheaper to buy books from Amazon.

Much as many of us would like to support local businesses and employment, the cost differential is a big factor in deciding whether to buy locally or buy from overseas. Even adding in the shipping charges, it’s often still cheaper to buy direct from overseas. Go figure…

Anyhow, this preamble is to let my fellow Australians know that there is now a local alternative to Amazon that will not only credit you with any price differential between their prices and Amazon prices (+ shipping), but add 10% more to sweeten the deal if the total purchase is more than AU$50 and delivery is to an Australian address. The online retailer is http://www.fishpond.com.au. Oh, and they take PayPal too — Amazon doesn’t.

Here’s a breakdown of the cost differentials on a set of five books I ordered recently — click the image to see it full size.

Book prices: Comparison

Book prices: Comparison

The individual prices of the books are MUCH higher in Australia, even accounting for the exchange rate. And the two main Australian booksellers — Angus and Robertson (A&R) and Dymocks — didn’t even stock some of the books in my list (highlighted in red) and still their AU$ averages for the books they *did* have were some $10 to almost $20 higher than Amazon’s AU$ equivalent, even allowing for the cheaper shipping rates from A&R and Dymocks.

Fishpond has no shipping charges on orders over AU$50 (an easy target to reach for books!), accepts PayPal as a payment option, and has a ‘Better than Amazon’ guarantee that credits you the difference PLUS 10% on your next purchase. Gotta be happy with that! I get the books I want, with the order filled by an Australian company employing Australians, at a price that now beats Amazon.

Service

Fishpond have very clear order tracking facilities on their website. I ordered on a Saturday evening, got an immediate (automated?) reply listing the ordered items and expected delivery times. I received an email first thing on the Monday morning telling me that one of my five items had been shipped, with an expected arrival date later in the week.

Update: My first book arrived within the time frame they said — they said between Friday and the following Wednesday and it arrived on the Monday, right in the middle of the expected date range. I’ve since received notice that my other books are on their way and should be with me later this week or early next. Update: And they were!

One small issue…

Their Better than Amazon guarantee? Well, I didn’t quite get the credit I had expected, so I emailed them. I’ve had quite a long email conversation going with them (this is good — it means they monitor and respond to their emails), and the upshot is this: They calculate the Amazon shipping costs based on a single book in a single order (i.e. almost AU$12 PER BOOK instead of AU$6 per book plus another AU$6 for the order). This is NOT clear on their website which states (as at August 18, 2009):

If you order a book where the total cost (including shipping fee) is more expensive on Fishpond.com.au than Amazon, we will credit your Fishpond account with the difference plus 10%. The guarantee is valid only for books that are destined for Australian addresses where the cost of that single book (including shipping fee) is more expensive on Fishpond.com.au than Amazon.

After quite a bit of to-ing and fro-ing with cost breakdowns, they  confirmed that they calculate the Amazon shipping based on a single book per order rate, NOT on a single order plus the number of books in the order. This means that I was credited with about $20 less than I expected.

Now, I have no problem with them setting the calculation rules — it’s their business, after all. But I have suggested they make the shipping calculation MUCH clearer on their website. And, if you know me at all from the posts on this blog, you’ll know that I even suggested the text they use! ;-)

The guarantee is valid only for books that are destined for Australian addresses where the cost of that single book (including the single order shipping fee plus the book shipping fee per book) is more expensive on Fishpond.com.au than Amazon.

I wonder if they’ll make that change? It’ll save them answering emails from pedants like me who DO check the details and ask questions. I’ll check back in a few weeks…

[Links last checked August 2009]