Advanced visual editing with Leah Guren at tekom12

Leah Guren presented a fast-paced, entertaining session full of relevant tips to improve visual editing in documentation. While some of her advice refers to page-based deliverables, most of it also applies to online output styled by CSS.

First, Leah showed how good layout improves usability, while poor design actually hurts the success of your documentation:

• Good design means to apply layout that supports the document’s meaning. So use numbered lists for sequenced information, bullet lists for unordered information and tables to (visibly) structure information.
• Poor design means information is hard to find, hard to identify and simply looks unprofessional.

To apply good layout design, you can use 5 principles which make up the acronym PARCH:

1. Proximity.Ensure that items and information that belongs together appears together:
   • Place headings closer to the text they belong to below than to the text above.
   • Arrange list items in chunks, so each item is easily recognizable as a unit of its own.
   • Offset individual paragraphs to clarify paragraph integrity.
2. Alignment. Ensure that vertical alignment uses few, sensible points of reference, so bullets and numbers are indented to one vertical line, the list items introduced by bullets and numbers to a second vertical line. Also ensure that text flow in tables is clear and it’s easy to identify which table items belong to the same row.
3. Repetition. Repeat visual patterns to signal intent and to ensure consistency. This applies to how you use colors and icons and where you place items within a topic or on a page.
4. Contrast. Apply contrast to focus the reader’s attention. For example, use larger and/or bold fonts for headings.
5. Hierarchies. Use hierarchies of topics and sections to nest information. This also means to avoid single children of parent topics, because you logically cannot divide a chapter or section into just one sub-section. (As a solution, you can either move the child topic to the parent level, or if more child topics are on the way, have a placeholding topic that introduces or previews the forthcoming topics.)

Then Leah offered some additional tips:

• Use icons to allow for quick filtering. Like a Thai restaurant that marks hot dishes with icons of one or several chili peppers. Or vegetarian dishes with a leafy icon.
• Choose your fonts smartly and consistently.
• Don’t design for exceptions. For example, don’t create a standard table with wide cells, just because you may have one or two cases which otherwise need to wrap around.
• In headings and paragraphs, apply white space only above for consistency.

And as final recommendations:

• Learn about design – it’s pretty easy already with stuff you can find on the web or paperback books.
• Ensure you get and stay involved in the design of your documents.
• Experiment and try new things – be brave, but stay sensible.

Advertisement

Leah Guren’s Fish Tale at TCUK12

After opening remarks by conference organizer David Farbey, Leah Guren‘s keynote relevant and entertaining keynote address presented several lessons from the animal world:  A Fish Tale: Improve your Career by Watching Fish!

1. Take a leap of faith – like salmon. It simply takes some guts and a little bit of faith that tech comm is here to stay, else you won’t be able to make a long-term plan and get behind it.
2. Stay in school for better chances of survival – once you took that leap, keep honing your skills, keep developing. There are lots of ways and many don’t require the same amount of time and money as going to a conference, whether it’s e-zines, forums, user groups or webinars (some excellent ones are actually free!) Be sure to make your professional development part of your regular work schedule.
3. Invest in better PR – the difference between a carp and coi is mainly the prize tag – which is thanks to better PR for the coi. Communicate your value that you bring to the company and to its customers. We know how much words matter, so we can do better than calling ourselves technical writers. “Information architects”, “content strategists”, even “technical comunicators” can make more money.
4. Find the right stress – (sorry, I forgot how this related to fish… 😉 ) Tackle your fears, get a new challenge and pick the kind of stress where you’re still in control, feel stimulated and can grow.
5. Active swim in a larger pond – because like a carp you will grow (professionally) in relation to the size of your “pond”. Find opportunities for growth how you can be the expert in your environment.

I’m sure I forgot a couple of Leah’s lessons. Nevertheless, I want to add an additional lesson that I’ve found important: Know the secret of the birds. That means know how your enemies tick, so they don’t eat you. Or if they’re not threatening: Seek heroes outside of your immediate field. Sure, you won’t be able to fly like a bird, but you can still find birds inspiring.

Leah Guren’s Tales of Terror: Avoiding Project Disasters at STC12

Leah Guren presented a spunky, fast-paced session of project train wrecks that offered many lessons to managers and writers in tech comm projects. She presented disasters in five categories: Communication, people, politics, implementation and global issues.

“Failure to communicate”

When poor communication derails tech comm projects, it’s often due to missing information. Specifically, a project may have failed to ask the right questions (almost like performing due diligence) or failed to insist on getting the questions answered by the subject-matter experts or the specifications.

To prevent this problem, don’t write blind! Ensure that the project is clear not only on the product, but also on the users, their scenarios and workflows. This is a tricky issue that it afflicts even experienced tech comm’ers who may be tempted to wing it. But a checklist can help you to cover all your bases.

Of monster managers and quirky SMEs

People can jeopardize documentation projects, especially if they bring together people who don’t work together in projects very often. As a tech communicator, you might deal with an annoying monster manager breathing down your neck one minute and placate a quirky subject-matter expert the next.

Leah’s advice was straight and matter-of-fact: You can’t fix crazy, so don’t take it personally. You might even find yourself documenting irrational processes and workflows.

Of stakes and turf wars

Politics can endanger projects when agendas clash and turf wars arise between fiefdoms. This is actually the reason why so many organizations still run a balkanized business where development proceeds in distributed siloes. The resulting documentation often perfumes the pig though it can hardly help being inconsistent or disparate.

Consider carefully whether it’s worth the extra effort to try and clean up broken workflows and GUIs after the fact – or if you even have the leverage and the clout to be successful.

Of implementation constraints

Implementation can throw a wrench into a well-planned project, when you find you lack skills, resources or access to such. Sometimes you’ll see warning signs, such as “scope creep” when a project quickly becomes more complex than you thought originally. For example, Leah talked about a project which was to cover a complete product overhaul – and an SAP integration on top of it.

This is a case for a senior stakeholder or manager who needs to assess the situation and who can hopefully reschedule tasks or reassign resources.

Of intercultural complexity

A recent, often unexpected problem in tech comm is complexity due to globalization. Global business often doesn’t scale seamlessly, and tech comm (as all culturally contingent practices) even less so.

If your project involves countries, markets and languages you haven’t been involved with yet, take extra care. However, as companies find out again and again, there seems to be no fool-proof way to address this issue, other than trying to look at similar case studies.

Solutions and remedies

Leah held off suggested solutions until the end. The good news is that many projects can address many of the issues to an extent with standard project management tools and best practices.

• Use a project check list that defines scope, deadlines and involved participants, incl. their roles, goals and expectations. Include also SMEs and other stakeholders.
• Track project status meticulously and insist on regular reporting – from participants and to the steering committee.
• Have a contingency plan, if at all possible, which can buy you extra time or replacements for people if you need them.

Salvaging wrecks

But the best-laid plans don’t always guarantee success, so you might find yourself with a project train wreck that needs salvaging. Leah’s advice, at least to me, wasn’t revolutionary or new, but rather an encouragement to stay honest:

• Don’t hide from problems or difficult people. They won’t get better and they won’t disappear by themselves. Face them and address them as soon as possible. If nothing else, you’ll sleep better.
• Cut your losses, if you have to and find the right time to cut your losses, before you throw good money after bad. If you, be clear to everyone (including yourself) what went wrong and why.

The assurance of coaching

After her presentation (which already included several case studies that I have omitted above), Leah solicited further case studies and problems from the audience. This rounded out the session quite well which felt like coaching on speed.

For me, the most important take-away was that projects can and will go wrong for all kinds of reasons that are beyond our control. But if we are alert and honest to ourselves, we can salvage most of them, wrap them up with decent success and saved face.