Session 2 Summaries – 25 January 2014

This is where the Notes from session 2 will be posted.

Visual presentations – writing content that isn’t text

Scribe: Maria Rodgers

  • Have you used SVG? People are interested to learn about it and use it
  • Feedback on videos – they are too slow for some people; other people only look at videos
  • Make developers sit down and record the final walk through as part of definition of done
  • HTML5 – you can loop through gifs – low cost entry for a video
  • Adult attention span for video – Microsoft research showed 3.5 minutes is about ideal…
  • – shows text used in video – you can click to go there in the video (outline for video)
  • Screenshots: marketing people want it. Good for low-entry or young learners
  • Tools – what do you use and like?
  • Illustrator
  • Photoshop
  • Snagit (easy)
  • Frame maker drawing
  • Visio
  • Add graphics to PDF for edit
  • Adobe after effects
  • BUY a vector graphic + tweak it.
  • Bad for translation – localization – $$$
  • Audiences
    • Expert
    • Check list
    • Safety + delivery compliance reminders
  • Training – level
    • Drill-down details
    • Screenshots
    • Planned redundancy
    • Considering using iconography
  • BIGGEST Challenge
    • Time – takes a lot of it to do graphics
    • Skills (difficult)
    • Standards (simplistic? Perfection?) education leans towards words
    • Lack of precision
  • SKETCH-NOTING – Concept of drawing your notes as you can to develop the visual pact of your mind.

Going Mobile

Facilitator: Nikki Davis

Scribe: Greg Urban

Content for mobile

Maxwell Hoffman and Joe Welinske

“Strategies for UDVS in interchangeable commands”

a webinar on how to write our xml with variables describing the gestures used on the devices.

They used a DITA table.

Moving content to mobile is not just moving your documentation to a mobile device.

What is apparently going to be coming is the interaction between an application and documentation meaning, if a shopping application knows that our location is at home it might present you different information than if it detected that you were in a store. “I see you are on aisle J, ?? you go to aisle J, we can offer you a coupon good for 50% off of bath towels”

  • Adaptive/responsive HTML5 outputs are the easiest.
  • Search engine optimization
  • Adobe TCS 5
  • Framemaker 12 can output HTML5
  • Robo Help II can output device/screen size specific resolution for say an iphone.
  • Implied need for analytics
  • Maxwell Hoffmann pointed out users have different attention spans for drilling into a website.
  • Shorter attention spans for smaller devices implies that it might be good to present information in a different order to a mobile device than to a larger-screened device.
  • Philosophical moment
  • Discussion about how users on mobile devices seem to have less awareness of their physical location. Perhaps the involvement with mobile devices is over-prevalent. There may be some relevance to how we write for mobile users – but it was not clear.
  • Definitions:
  • Ebooks – general online book format
  • Epub – specific format – content flows and can have uncontrolled formatting
  • Binder – big thing due to Amazon

Technical editing fundamentals

Scribe: Portia DiPasquale

“The Baby Boomer Exodus” by Ken Ball + Gina Gotsill

  • Found success in the editing process:
  • Editing: do you end up coaching? The technical space has many non-native speakers and engineers mark-up – helps to have writer fix mistakes, work shops, how do you instruct writers who aren’t local?
  • Engineers write functional specs, the next person who looks at the doc can compound the issue if it is misinterpreted. Convincing your company that clean specs is important will be crucial but, how do you do that with engineers?
  • Product review cycle: if you have a good process of review, the right person does the review with a good workflow it will be seamless. There is an element of negotiation + translation.
  • Add comments
  • Track changes and give writer sole responsibility of doc. Ask questions: if anything is ambiguous, you are in trouble.


  • Content and am I doing it right?
  • Typos, spelling grammar, capitalization
  • Company names, formatting
  • Does the piece actually complete intended goal is this a style guide?
  • Is editing fact checking?

Lone writing: all my known mistakes, bad habits

  • Find things that a real scan wouldn’t find
  • Scan each line
  • Automated search and replace tool
  • List of words that are typically misspelled
  • Dangerous: automated spell checkers
  • Many words and phrases can go past spell check
  • “wreaking havoc” insightful: starting a riot
  • Flavor: flavor
  • Paring knife idioms: native speakers
  • Idioms: don’t belong in technical documents editing tools
  • upload content, it analyzes it
  • Efficient editing practices: newer done with a document, you just run out of time
  • Foster a love of documentation and writing. Help your writers understood why they need to make changes.
  • Editing tips:
  • What is efficient editing? Systematic


  • Mechanical editing: word by word
  • Second pass
  • Be consistent
  • Levels of Editing: Don’t want to duplicate work.
  • How to give feed back without offense: style guide ?? to refer to
  • Checking your writers helps make the editing process easier
  • Checklist: go through each one, one at a time
  • Your understanding will grow over time, you’ll soon have a bigger picture. Part of editing is reconciling different writers ideas into the concise idea.
  • Part of being consistent is knowledge of the topic. Technical communications are looking for what is different, what doesn’t make sense. Everyone has a blind spot about their subject matter. Your job isn’t to be a subject expert, it’s to translate the content into something that makes sense.
  • Know your acronyms! Spell it out the first time you use it.
  • You have treat each writer different depending on the subject: phone calls also
  • Google documents:
  • Talk, write and agree at same time

Thinking like a librarian

Scribe: Jay E. Martin

  • Means metadata, which includes further search terms
  • Librarians are heavy users of metadata and popularized it.
  • DITA needs a CMS
  • Discussion members plan to implement a taxonomy, researchers, member had worked with a data librarian, proposal writer, job seeker
  • Recommendations: breadcrumbs, rank the content
  • Purging? Same data but search a date range.
  • More obsolete doc to another server to keep it out of search results.
  • Visit your local library.
  • Get the knowledge in your head into the metadata
  • Get metadata from indexing, brainstorming, data analytics of user search phrases
  • Notes on card catalog were early data analytics
  • Different perspectives on info require different metadata.
  • One member is trying to link terms in taxonomy to other terms

Controlling/harnessing MS Word in the move to XML

Scribe: Sydney Thornton

Our person had newly emerging techniques to corporate answers.

1. Components of getting control of word

  • Different to get control of word features – so flexible
  • What’s the architecture for the information
  • Word XML doesn’t constrain sufficiently to put into a business environment/situation
  • A billion people use word, some of structured and semi structured content

2. Goals – better content

  • Implement a standard into architecture
  • Publishing to multiple media
  • Information re-use
  • Improve brand
  • Save money
  • Solution

3. Word – plug-in or

  • Not ooxml
  • Controlled XML is the ultimate goal
  • Word conversion then use XML editor
  • Legacy content is always ?
  • Standard should probably co-exist with XML editors

[hr type=”double”][/hr]

Content vs. documents

Scribe: Robin Smith

  • Think of where content is consuming – in training, marketing, etc. useful concept to embrace
  • What are the users’ needs? – deliverable requirements. Documents is a chunks of content.
  • Dynamic content – based on location – or time.  e.g., mobile phone web access.
  • Content can be used in many other places than document or pdf can.
  • Responsive design/responsive content
  • “content reuse is the sincerest form of flattery”
  • Room in most organizations for both mindsets – content and documents creating accessible content takes work.
  • Things that communicate are content – such as aps.
  • QR code – content or document?
  • Google glass discussed