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

Strategic Technical Communicator panel at tekom12

Marijana Prusina, Nicky Bleiel, Sarah O’Keefe and Dr. Tony Self pooled their experience in an interesting and versatile panel session about the more strategic aspects of our profession.

The Strategic Tech Comm panel (photo thanks to Axel Regnet)

It was not so much a discussion as a fast-paced session of the experts sharing their thoughts on strategic issues and problems, so I’ll simply list some of the insights:

• Domain knowledge for a certain industry (as opposed to general tech comm skills) can be a great asset that you can use to build a career on, but it’s not necessary to become an expert in any one domain.
• To get a mandate or money from management, don’t argue in terms of quality, but rather in terms of cost: Show how improving documentation will either reduce cost or create additional revenue.
• Freelancing can work well, but you will need some things which are less essential if you are employed:
  • Considerable project management skills – even if only for your own projects
  • A good network of satisfied customers, other people who know and like your work, and other freelancers with whom you can exchange tips and tricks – and maybe even projects if they’re better skilled to take them on or when you are busy.
  • A snappy definition of your core services, skills and profile.
• To improve the reputation of tech comm and exert influence in your company, try these strategies:
  • Volunteer, if you can afford to, whether in a professional tech comm association or a standards committee.
  • Underpromise and overdeliver on your deliverables – and meet the deadlines you agree to.
  • Write a book – but be aware that you’ll mainly do it for marketing and influence: It’s a lot of work, and it won’t make you rich.
  • Be the advocate of users, who are satisfied, more productive and less costly to your tech support thanks to good documentation.
• Take all the training that makes sense to you and that you can get. Don’t forget about domain skills and software-related skills, for example, for API documentation. When training, keep in mind your resumé and what value you will add to your customers or your employer by adding a certain skill.