Posted on 7 September 2016 by Kai
So our company has an elevator pitch competition. The task is to explain in 30 seconds “What does our company do?”
The submissions indicate that “to explain” means different things to different people. To some, it means “to describe or summarise information”. To others, it means “to translate and clarify for others”.
The two meanings reach different audiences with different levels of success. Description and summary are best when you have a similar background and outlook as your audience. Translation and clarification are best to bridge differences between you and your audience. Such a difference could be much vs. little experience with a product or knowing how to set it up vs. having to use it every day. To bridge this difference, you have to put yourself into the users’ shoes and remember how it is not to know all the things you know now.
Technical communication skills, our experience when crafting content, and the way we can structure information let us excel in the translating and clarifying. And the better we know our audience, the better we are at it.
Developers and testers who contribute to user documentation frequently deliver very good descriptions – and technical communicators can help them by translating and clarifying them further, if necessary.
We often hear that “everybody can write”. But what it means is that many people can describe (and some don’t even do that very well) – but few can clarify as well as a technical communicator.
If the distinction between describing and clarifying resonates with you, I’m sure you can think of more examples.
Filed under: motivation, technical communication, writing | 2 Comments »
Posted on 6 October 2012 by Kai
In his session Letters From The Editor, David Farbey talked about what editors do, what they can do and what they can do better.
What editors do
Basically, it is the job of editors to mediate relationships. They mediate the relationships between the writers, their content, their audience and their organization (such as a company or institution).
More specifically, they still do much of what Robert Van Buren and Mary Fran Buehler laid out in their seminal booklet Levels of Edit of 1980 (a PDF version is available online). Mind you, much has changed since, but many of the basic principles still apply. So David took his cue from the 9 levels of edit to propose 3 classes of edit today:
- The policy edit is for coordination and planning. It ensures that the content is appropriate to the organization and its audience, that it complies with the organization‘s policies and strategies.
- The copy edit handles all the technical issues of content, from spelling and punctuation to formatting and textual integrity. It ensures that the text is functionally correct and clear.
- The developmental edit addresses the content itself in the last and most important stage. It ensures that the language is comprehensible and presents the text’s substance appropriately and clearly, whether it is a concept or a procedure. (This is not the same as a content review! A subject-matter expert reviews whether content is correct and complete, while a developmental editor ensures that such content is presented in clear and comprehensible language.)
All three classes of edit occur at the same stage in the content workflow:
- Policy edit: Author and editor plan content production.
- Author writes content.
- Subject-matter expert reviews content.
- Author corrects content according to review.
- Developmental edit: Editor edits content.
- Author corrects content according to edit.
- Copy edit: Editor proofreads content.
Advice for editors
- Check the text and the publication, not the product or the facts that are described in the text, that’s the task of the reviewing subject-matter expert.
- Offer constructive criticism, don’t evaluate or grade the text.
- Mentor the writer, if necessary, don’t manage the writer. If you are his or her manager, put on your editing hat, not your managing hat.
- Create and apply guidelines and policies:
- Create and comply with a corporate style guide as a searchable collective memory to guide the work of writers and editors alike.
- Agree on who has the last word.
- When editing topics in structured authoring:
- Edit in chunks
- Add a step in the workflow before the copy edit: Editor or writer compiles document
- When editing in an agile environment:
- Consider when a content item is shippable
- Consider when the document as a whole is shippable
- Change the workflow so steps 2. through 4. above become: Write and review in sprint.
Filed under: conferences, editing, reviewing, style guides, writing | Tagged: David Farbey, TCUK12 | Leave a comment »
Posted on 9 November 2011 by Kai
The skill of technical communication is to create a context in which other people can work. – This concise insight helps me to stay focused on my users and their tasks, even if it’s not totally original.
I came to it via an article by Tim O’Reilly in his Financial Times article “Birth of the global mind” where he quoted Edwin Schlossberg:
The skill of writing is to create a context in which other people can think.
Filed under: articles, motivation, quote of the day, technical communication, writing | Tagged: Edwin Schlossberg, tim o'reilly | Leave a comment »
Posted on 5 September 2011 by Kai
Are serif fonts easier to read than non-serif ones? No, is the conclusion in Alex Poole’s exhaustive post.
After reviewing more than 50 studies, Alex comes to the conclusion that “serifs or the lack of them have an effect on legibility, but it is very likely that they are so peripheral to the reading process that this effect is not even worth measuring”.
Serif vs. non-serif fonts as illustrated by Wikipedia
Thanks to Chris Atherton for pointing me to this post which perfectly complements one of my most popular posts: Ragged-right or justified alignment?
I must admit this came as a surprise to me, since I always liked the argument “Serifs are used to guide the horizontal ‘flow’ of the eyes”. But unfortunately, simply liking an argument doesn’t make it so. 🙂 It might just be a case of confirmation bias, as in this case…
Today’s bonus link is to a cool, comprehensive article in Smashing Magazine about typography including justified text, hyphens, dashes, smart and dumb quotes: Mind Your En And Em Dashes – Typographic Etiquette.
Filed under: academics, writing | Leave a comment »
Posted on 3 February 2011 by Kai
Becoming a better tech writer requires practice.
Mike Pope, tech editor at Microsoft in Seattle, has a brilliant blog post about 12 ways to practice tech writing. The catch is he means “practice” like a musician, so you learn to do stuff better than yesterday – instead of just doing the same things over and over.
Over the last years, I’ve tried all 12 ways, and they’ve all helped me to become a better writer. And most of them can be fun, too, at least most of the time… 🙂
Here are just six of the ways as a teaser, but I highly recommend you head on over to Mike’s post to find out about all of them with details and examples.
1. Read other technical writing attentively.
2. Read about writing.
5. Writing something outside your usual material.
7. Edit someone else’s work.
10. Learn new tools and new ways to use your existing tools.
11. Talk to other writers.
Filed under: blogs, creativity, editing, lone writer, motivation, tools, writing | 5 Comments »