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

Session 1 Summaries – 25 January 2014

This is where Session 1 Notes for tomorrow’s event will be posted!

How to use video  effectively in TC

Scribe: Lori M

Questions – how to use videos to perform tasks

  • Keep videos short
  • Where most helpful – concept overviews; 50,000 views of a task. People tune out of lengthy task
  • Good writer, network architecture important. better than a written description or text with Pics
  • Video is complement to written doc, not a replacement
  • Used 70 sec videos to describe the steps in a process (best to keep it short)
  • Video in cloud-based help system
  • Scripting process? Story boards in PPT (desc of visual + accompanying steps). Much review alone or story board stage (more economical).
  • Writers recover screen captures
  • Takes a long time to prepare a 70 sec spot
  • Captivate & camtasia are popular tools
  • Users see screen captures as well as taking head. Seeing a person makes video more engaging. Talking head videoed separately from screen captures
  • Adobe Premier, After Effects also used
  • Creating videos of complex process – how to decide how to split up a complex process
  • Use Google Analytics to find out viewing patterns
  • Embedding videos into help – help is Eclipse-based, videos are hosted by a 3rd party server.
  • Item to measure engagement? It’s subjective
  • How do you decide who gets video presentation? At vmware, highest-priority topics were for capturing on video
  • Added navigational aids to help users find content on video
  • How does interest level in videos change over time? Steady growth in videos on YouTube channel
  • How does training assign model affect video design? Training videos are slower
  • How to decide which method for a procedure to select? Customers involved in beta tests. otherwise, talk with product managers and marketing. Be consistent in the approach you take.
  • How to get started doing videos? Depends on the extent to which you want to learn. Need to learn video capture software. Be sure to strive for quality of AUDIO.

Get good voiceover audio. Tripod important also!


Scribe: Liz Miller

Facilitator: Jo Ann Grey

The Final “Recommendation” (Approval due in 2022)

  • 5 – Separates the structure from the content; uses
  • Biggest – New structural tags added; presentation separated
  • 5 – Video, local storage other media-handling now handled
  • 5 – device responsive; different presentations
  • Code to query the browser for CSS to use
  • Reads existing (prior CSS) and allows viewable area for the content; resize browser resizes view port HTML5 rules for viewport in code. No more pixel-based better scaling; more useful for mobile, various sizes.
  • “Adaptive content” is great for trainers using a variety of mobile devices to present instruction
  • It’s becoming a normal output for a variety of popular tools
  • 5 tags not case sensitive; no strict doc type, more flexible, allows backwards compatible HTML version.
  • Runs on any browser; content-centric display
  • (headings, lists, etc. taken care of consistently)
  • Local custom CSS rules can be embedded in HTML5 as today; but external CSS better ePub3 is based on HTML5 – runs on any device except kindle.
  • Not a skill set for recruiters per Andy; also…
  • TREND: Adobe Flash will be slowly replaced by HTML5; already iOS does not
  • Youtube is non-flash – google supporting 5 support it
  • HTML5 focus on web-based videos with built in tagging; then you wouldn’t need the add-on for the browser external video display tools play outside the browser, Real Player, Quicktime. Not HTML5-based
  • Display in browsers “should” render faster due to less non code loading, add-ins. If content load high, may see some slowing. CSS file gets cached for all pages to use on access with no added download
  • HTML4 conversion/mapping? Possible but not easy
  • 4-Tables and framesets hide content from accessibility
  • 5-Table tag facilitate SEO; separates perspective structure out
  • This makes content more findable, better accessibility layout comparison to printed paper output – pixel perfect
  • With HTML5 “content is king” after all
  • Mostly Pam and Chuck sharing knowledge
  • Today’s HTML tools all going to HTML5 compatible

Reusing content  with tech pubs, training, marketing support and other organizations

Scribe: Tonie

How to organize other than DITA?

  • Tools, procedures
  • Share Point?
  • How Structured/Purpose meaning
  • XML is where everything is headed – portability
  • Based on Content newability
  • Language – marketing vs Techpubs
  • Not always structure
  • Who’s sharing
  • Training and Techpubs(inotructional + Techpubs)
  • Sales, product marketing, specs, training
  • Crossing silos by conversation, communication across teams
  • Functions of the organizational reporting structure
  • Goals compatibility issue – Engineering vs. Services
  • Partnership is independent of tool
  • Size of company doesn’t matter/it’s management and individuals within the enterprise.
  • Industry – e.g. mfg info parts data, etc. need to broad cast info.
  • Depends on who the content has to support.
  • Developers, tech does, training use same personae
  • Earlier in onboarding process
  • Core concepts cross borders
  • Start with glossary
  • More consistent branding even if give the various phrasings
  • Change process
  • What documents change
  • Engineer out redundancies
  • Why changing UI in real time
  • Marketing and help desk into product development
  • All same flow
  • Feature or bug, ELSE:
  • Fix process, not just document when something’s not working
  • How do you know which document to choose if several depts. Have docs?
  • Need a process to use the tools ELSE, a bunch of tools
  • Doc – H Drive – Share Point
  • Share Point – align with interface
  • Standards compliant (ISO)
  • Audit trial – Build bridges
  • Starts with Risk analysis
  • Business Risks
  • Business Rules
  • Obsoletes documents
  • Templates
  • From training perspective user/consumer of content Informal sharing – Personal relationship
  • Pain needed, e.g. lawsuit
  • Who has the biggest risk factor or driving the single view of customer
  • Benefit – consistent message.

Strategies for using Bookmaps and maps in DITA

Scribe: Robin Smith

  • Key refs and book designed well together.
  • Key ref – Topic map
  • Collect – Key map
  • Key definitions in the map reference to it in Front matter
  • Key def = definition > filtering attributes
  • Key ref = reference > filtering attributes
  • Chapter, front matter, appendix – top level.
  • Relationship tables
  • Maps are the glue that hold the data together.
  • Topics
  • Root map
  • Chapter map
  • Scripting/leverage keeps in conversions
  • Link topics to define a hierarchy – this is what maps are – naming topics – good information architecture – style guides
  • Don’t use comas in names – use underscore!
  • Con refs and key refs as ???
  • Docbook to Dita – transformer
  • Basic Dita map to reflect
  • Book map – elements Front matter, chapter, ?? matter
  • Regular map – ?? publisher
  • Organization of Topic Refs
  • Chapter maps –  (All are topic refs in the end)
  • The key is to only use the maps ?? they are built maps have the name of the content.

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

Deep Dive into Adobe TechComm Suite5

  • Introductions
  • 4 people in attendance; Max is #4
  • Determine need of group
  • Jan. 28th webinar on the Tech Com
  • Misconception about product based on consumer usage 5 to 10 years ago
  • E-learning/training tech com suites
  • Fm          Rlt           CP
  • CP market leader screen capture other features
  • Fm 10 video/audio to help new user create fancy PDFs publish to epob kindle
  • Rlt import
  • Triggers and gadgets
  • Fm XML author 12

Writing/formatting best practices

Scribe: Julie Phaviseth

Tools: what should you learn? Desktop Publishing +?

  • DITA linking everything by its purpose, separating out your information into different types, self-contained, a way to structure your idea, not worried about organization and only worried about content without formatting. A tool where multiple writers don’t have to worry about details, can focus of writing far from universal.
  • Writing workflow:
  • Tech writing to non-native speakers: remember that you are speaking to a human and had to address the audience directly in active voice. Determine what you are trying to accomplish and what the reader needs to know.
  • What kinds of questions will a user have?
  • “Developing Quality Information” book
  • Volunteer with open source: Mozilla
  • As a user, some would appreciate knowing what they can’t do. Would help usability and findability of information: not necessarily a negative thing.
  • 5 w’s, keep answering what + why
  • Take a break and approach project with clean space, no clutter. Writing is best early or late in quiet.
  • The more you talk about a subject, the easier it is to write: exercise.
  • If you are feeling stuck, you don’t have enough info
  • Helps writing: peer review in the editing + review process
  • Vocabulary doesn’t help you in tech writing, so having a large vocabulary may hold you back. Simple, succinct writing… remove extra words.
  • Getting better about writing
  • Teen writing is creative writing, but, interestingly most don’t write in personal life

– Checklist: plan + write without rambling
– Self-edit: take time away from document, read aloud

  • Word counts look at small pieces of writing: sentences. Look to see if you repeat yourself. ?? every sentences adds to the conversation.
  • Word: readability score – help with translation
  • The most important piece of information should be at the end: sentences + paragraph.
  • Front loaded vs. back loaded information
  • Online articles: heading.
  • Findability is number one
  • Clear organization
  • Use of keywords
  • Blog “Every page is page one”
  • The title and introduction sets a person’s expectations.
  • Formatting: style guide, consistent
  • STC


Session Matrix – Saturday 25 January 2014

Session #1

  • How to use video  effectively in TC
  • HTML 5
  • Reusing content  with tech pubs, training, marketing support and other organizations
  • Strategies for using Bookmaps and maps in DITA
  • Deep Dive into Adobe TechComm Suite5
  • Writing/formatting best practices

Read the summaries from Session 1

Session #2

  • Visual presentations – writing content that isn’t text
  • Going Mobile
  • Technical editing fundamentals
  • Thinking like a librarian
  • Controlling/harnessing MS Word in the move to XML
  • Content vs. Documents

Read the summaries from Session 2

Session #3

  • Jobs/job search: How to break into a new industry; portfolios and how to construct them
  • Deciding what goes into a doc or mobile version of an enterprise software app
  • Documenting APIs
  • Metadata and categorization strategies
  • Taking your content strategy to rest of org
  • Improving search

Read the summaries from Session 3

Session #4

  • Leveraging LinkedIn
  • Content architecture and design
  • Document review process
  • DITA vs. Docbook
  • TC and Agile
  • Writers and product usability

Read the summaries from Session 4