Category Archives: book

Which books should Technical Authors read?

Posted on by
8

Woman reading bookThe bookshelves here at Cherryleaf are double stacked, and we’ve received another book this week to read and then store.

So it seemed like a good time to mention which books we’d advise Technical Authors to read.

This most recent book was published by XML Press, and their publications are well worth looking at. We have quite a few books from them. Some were review copies (i.e. free), and others were ones we bought.

Most Technical Authors use style guides, and both Microsoft and IBM publish style guides you should consider buying. Style guides help you make sure you’re using the right terminology. They can also help your manuals complement the big vendors’ documentation.

Cherryleaf offers a couple of Kindle books for a just a few pounds.

Then there are the technical writing “classics”. In this group, we’d recommend you look at books by Ron Blicq, John Carroll, JoAnn Hackos, Karen Schriver and Joe Welinske.

Specialist books like these are not cheap, unfortunately; a decent collection of technical writing books will set you back at least £100.

Which other books and authors would you recommend to Technical Authors? You can use the comments box below to share your opinion with others.

(Flickr image: Will Ockenden)

The best book for Technical Communicators in 2012

Posted on by
Reply

The best book I’ve read in 2012 wasn’t written for Technical Authors. It wasn’t even published in 2011. It was written by one my fellow speakers at the STC Conference in Chicago, and it was one that was the most thought provoking books I’ve read this year.

One of the subjects it explores is curiosity:

Continue reading →

How software users become champions

Posted on by
Reply

Matthew Syed is a British sports journalist and former three times Commonwealth Games gold medallist, who has been investigating what is needed to make people excellent at doing any task involving complexity.

He argues that natural talent, your genes, are far less important than many people think. What’s important is practising what you can’t quite do. He argues we grow if we test our limitations, because our body adapts.

So what on earth does that have to do with developing software and Technical Authors? Syed argues there are two opposing views regarding success:

  1. One “school” believes talent is what makes success. This means that if you fail, you believe it’s because you don’t have enough talent. Therefore, you’re likely to give up.
  2. The other “school” believes success is all about practice – the quantity of practice, the quality of teaching and the willingness to test our limitations. This means that if you fail, you believe you can succeed with more perseverance and effort. It’s an opportunity to adapt and grow.

I would argue the whole philosophy of User Assistance is based around the belief that talent is all about practice. It’s easy to forget that others may think it’s all about talent – your developers may believe some users fail because they are stupid, and some of your users may believe they’re just not good enough to succeed. It’s worth checking what they believe.

Another implication is that we should provide assistance and guidance to users as they are doing the task. We should try to avoid interrupting their flow. This suggests providing Help and advice within the application screens themselves.

Thirdly, we should praise people for their effort rather than for their talent.

Bounce

BBC Radio 4 Four Thought

What do you think?

Book review: Confluence, Tech Comm, Chocolate

Posted on by
1

I was sent a review copy of Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication, by  Sarah Maddox. It’s about using wiki technology for developing and publishing technical documentation, using the Confluence platform, the emerging trends in the creation of User Assistance and, in places, chocolate.

Confluence, Tech Comm, Chocolate

The book is aimed at three audiences:

  1. The person who isn’t sure what collaboration tools and wikis are, and is not yet fully convinced these are platforms they should use for producing and publishing technical documentation
  2. Someone who has used Confluence or another similar application, but sees themselves as a beginner
  3. Advanced users of Confluence.

The author manages to pull it off  - all three groups will find the book interesting and useful.

For the skeptics, Sarah raises and answers a great question:

Isn’t a wiki just a puddle of chaos?

The problem with the word “wiki” is everyone thinks of Wikipedia, with its complicated authoring environment and occasional errors. Sarah explains not all wikis are like Wikipedia, and how Atlassian, the makers of Confluence, struggles to describe the software (it currently says it “provides collaboration and wiki tools”). In fact, Confluence is a tool that can publish EPUB ebooks, PDFs, Word documents, HTML, DocBook files and, probably quite soon, DITA files. It has a rich text editor that looks like Word. It’s a wiki that doesn’t look like a wiki.

The book itself was written in Confluence. Comprising 477 pages, there’s a lot of “meat” in this book. We’d consider ourselves as knowing a lot about Confluence, having used it to build solutions for a number of clients, but there were many useful nuggets of new information.

Enthusiasm oozes through almost every page. That’s partly because Confluence is one of those tools that causes clients to get excited. They very quickly realise the potential outside of the original project. It’s also partly because the author is passionate about the subject.

Examples are built around a hero (heroine, actually) called Ganache, and this approach works well.

The book also looks at new trends in User Assistance – where technical documentation is going and how it will be created. A Cherryleaf article is mentioned in passing. It looks at working in an Agile software development environment, and how a collaborative authoring environment can help reduce the authoring bottleneck Agile can produce.

Sarah also highlights the weaknesses of authoring in this environment. There are issues around round tripping (and whether it’s needed or not), in particular.

Technical Writers will also have questions about translation and localisation of content, which is touched on only briefly. Publishing to .CHM files isn’t covered. However, there is a wiki that complements the book, so readers have the opportunity to raise these questions with the author (and discuss them with other readers) there.

If you’re interested in collaborative authoring, wikis, Confluence, chocolate, working in an Agile environment or where technical documentation is going, then it’s worth getting this book.

Book review:”The Content Pool”

Posted on by
1

I was sent a review copy of Alan J. Porter’s latest book, The Content Pool: Leveraging your company’s largest hidden asset. It’s a well written book that’s ideal for anyone who is uncomfortable about the way their organisation creates and manages its written content, as well as anyone who simply wants to manage their content in better ways.

The book identifies and takes you through the key aspects of taking control of your content. I liked the book for what it left out, as much as what it covered. Content strategy and content management are huge topics, and it’s easy to feel overwhelmed by it all.

He could have covered topics such as the difference between short term and long term information, the provenance of information, and the attention economy (illustrated in the video below). However, he was right to leave those topics out and keep the focus on the main issues.

Alan raises key questions (such as why are you producing this content?), and helps steer you to the answers. The book also contains many anecdotes and case studies that keep you engaged throughout the book. He keeps reminding you to check any content system you implement meets your business goals.

He states:

However, being realistic, very few if any, companies are going to leap immediately from undervaluing their content assets to having them overseen and cared for by the highest levels of the organizations.

At the start of the book, he lists many examples of where poor content has had a major impact on an organization. Unfortunately, I don’t think these will persuade a CEO who thinks content is not that important to change their mind. I suspect they are more likely to change their mind if they felt their content was causing them to be left behind by their competitors.

The examples of Disney’s (which is mentioned in the book) and Coca Cola’s approaches to content strategy are likely to be a more convincing argument – big companies using content to gain a strategic advantage. We’ve also found other motivating factors to be directors who feel they don’t fully understand how the organisation is doing (numbers can only tell you so much, and meeting people is time-consuming) and CEOs who feel staff are not ‘getting’ the organisation’s goals and direction.

The final chapter provides great advice on how to sell yourself, and the idea of content strategy, to the organisation.

The worst aspect of the book is its cover drawing – it’s the wrong image for a professional book such as this. So, don’t judge this book by its cover – it’s worth adding to your bookshelf.

New review of “Trends in Technical Communication”

Posted on by
Reply

Phil Stokes has written a review of our Trends in Technical Communication ebook in the Autumn 2011 edition of the ISTC’s Communicator magazine:

Overall, though, this book does what it promises to do. It provides an overview of trends in technical communication and sets out a vision for the future. If you are wondering what skills you are going to need tomorrow and where the future lies for our profession , this book is a good place to start.

Phil gave it 4 stars out of 5.

Voltaire, typos, and the jitters – writing the IBM Style Guide

Posted on by
Reply

This guest post is from Peter Hayward of IBM (UK):

Voltaire said that “the art of medicine consists in amusing the patient while nature cures the disease.” Technical editing is a bit like practising medicine. It has a focus on both prevention and cure, except we don’t have nature on our side. With editing, nature tends to maintain the status quo; if the doctor doesn’t attempt the prevention and provide the cure, the disease persists. Writers need some sort of guidance to help them through the minefield of trying to write consistently, clearly, and concisely, while still following all the rules that editors seem to enjoy imposing.

Like many organisations, IBM has made up its fair share of rules and guidelines. A council of about 15, drawn from across the company’s writing community, is charged with looking after them, making sure they stay consistent and up to date. These guidelines have been available internally for many years, but we recently recognised that this accumulated wisdom might have a use in the wider world of technical writing.

So a sub-group of editors from that Style and Word Usage Council set about turning the guidelines into something fit for publication, removing all the boring internal bits, making sure we didn’t upset any sensibilities, or run foul of our legal overseers.

IBM uses DITA markup these days for most technical documentation, so we decided to follow suit with our scribblings. As well as providing our text to the publishers in that format, we were able to transform it daily into HTML and put it in a structured help system (“information centre”) based on Eclipse so that we could keep track of what we were doing.

I guess that to a big publisher, our little book was just one more title on their list. We naturally saw it as much more. Although, thinking about it, such a book actually is different from other titles, which is making me just a little apprehensive. If you want to use trendy jargon, you could say it’s a “metabook”, writing about writing, which means that you’re inevitably setting yourself up for a fall. If you spot a typo in most books, it’s usually little more than an annoyance. Typos and mistakes in books that purport to tell the reader how to write properly, invite a rather different response.

So if you do get your hands on a copy of the IBM Style Guide (“available from all good bookshops”), please be gentle. We tried to persuade the publishers that it was you, discerning author, who we were writing for, and not your average “punter”. OK, so it’s not fair to pass all the blame for errors to these editors’ editors. But I’m a little nervous. Of course it’s full of good stuff, well written and without blemish. Really it is. But I just have this feeling, that as the very first copy I handle falls open at random…

New review of Trends in Technical Communication – Rethinking Help

Posted on by
Reply

David Kowalsky has reviewed “Trends in Technical Communication – Rethinking Help” in the latest STC Puget Sound Chapter’s newsletter.

Trends in TC ’s good introduction explains this eBook is a collection of articles and selected excerpts on recent trends in software technical documentation “to help those involved in developing software User Assistance, in all its forms, determine a strategy for the future.” The descriptive headings break up the content, and for the longer articles, there is a predictable and helpful format of including an introduction, summary or conclusion, and references or further reading.

We’ve just published an ebook called Trends in Technical Communication – Rethinking Help

Posted on by
Reply

We’ve just published an ebook called “Trends in Technical Communication – Rethinking Help“.

Many people in the field of software and technical communication are asking: Couldn’t we do a better job at helping users when they get stuck?

This 762 page book is a collection of articles and selected extracts from books that have looked at some of the major trends in software technical documentation in recent years. Its purpose is to help those involved in developing software User Assistance, in all its forms, determine a strategy for the future.

There are more details at:

Don’t have a Kindle? No problem – you can view it on your PC, tablet or smartphone.