Monthly Archives: May 2014

STC Conference Notes from Wednesday May 21th

Here are my notes from Wednesday

8:30-9:15 Creating Help Systems for the Modern User – Kevin Siegel Founder of Iconlogic Kevin has been creating help systems for 15 to 20 years.  This session is about help systems that are successful and not successful.  He is big on Captivate.  It was a good session and very well attended.

  • This session will cover
    • attention span
    • no scrolling
    • engage your user
    • planning a
    • outputting
  • Most people will not scroll to get through your content.  They will give up and go to another topic.
  • Graphics are ok but videos are better in your content
  • Videos should be links and not embedded in topics.  This will reduce the scrolling.
  • Kevin is using a button that opens a menu with links as an example.  This reduces the clutter on the screen.  In testing 90% of people felt more comfortable seeing a menu rather than a dialog.
  • Short and sweet videos is key
  • Videos should have length of time so the user has a good idea of commitment
  • 15 seconds is home long you have before your average user starts to lose interest.
  • Google glass and heads up display ( HUD) are both examples of very small displays for content
  • e-ink is another small format display
  • More and more people are accessing content on a mobile device.
  • In testing an overwhelming number of people want demo videos and not interactive videos.
  • Remember to add alt text  to graphics and videos for accessibility.

He ended with a RoboHelp demo.

9:45-10:30 Beyond the Bleeding Edge – Neil Perlin This session was pretty good to just listen to.  This is a case study of a guy that needs to get his content from Framemaker to a Salesforce knowledgebase.  He wanted to populate the knowledgebase with his content to help out the support people.  When they get a call from a customer they can see if the solution exists in the documentation before they write a new solution.  He mentioned the support people have access to help but they never really look at help and he was hoping to get his help content a little more in the face of the support staff.   There is no easy way to populate the knowledgebase in this way his so he had to come up with this work around. I’ll get the link to the slides.  He had to use a list of tools to make this happen.  The process he came up with is very convoluted.  If anything is off or wrong along the way it will not work.  Lots of prep needs to happen to the Framemaker files before you can start the process. One of the many problems I can see is that you now have split the source and you have two streams of content to maintain.  So if you have an update or issue in the Frame docs you need to make the change in two places or run the process over again.

11:00-11:20 Applying Learn Principles to the Documentation – Alan Houser

This was a nice presentation. Lots of people and lots of good info. Alan does a good job with his presentations.

  • What is lean
    • maximize customer value
    • minimum waste
  • Big ideas
    • build/measure/learn
    • get out of the build talk to the customers
    • min viable product
    • pivot being able to change direction if needed.
  • What we tend to care about
    • deliverables
    • schedule
    • tool
    • origination structure
    • office  politics
    • legacy for formats
  • The customer only cares about getting the information they need and getting the issue resolved so they can get back to work.  Help cannot stand in the way of this.

This is not the time for “We’ve always done it that way” thinking

  • How/When does your team pivot
    • Budget cuts
    • Re-org
    • Reduction in force

Try to be in front of this and pivot before these happens.

  • What do we measure
    • Number is pages
    • Number of topics
    • Words/topic
    • Word count
    • And so on

Customers don’t care about any of that.

  • At the end of the day nothing is better than getting closer to your customer
  • Documentation Waste is if it does not provide customer value then it needs to be removed
  • Let it go!  The fancy formatting and perfect page layout means nothing if the customer does not get the information they need
  • Make sure you always ask ‘how is this providing value to the customer’

Recommended books

  • Lean Thinking
  • The Lean Startup
  • Lean UX
  • Running Lean

11:35-11:55 The Creative Habit – Kelsey Ruger This session started early and I missed the very beginning.  It was a great session with good slides. Because it was a short session and the speaker was so engaging it was best to just sit and listen.  Not much of an opportunity for notes. Search around and see if you can find his slides.

12:10-12:30 The Cracker Jack Theory of User Assistance – Ray Gallon  This was another good session and the last session of the day.  It was very well attended and the speaker was great.  Lots of knowledge.

  • Building cognitive demand.  How do we do that in UA?

He used ‘How do you use the camera’ as an example

  • How do I take a good photo what does that mean start using the camera
  • Hands on practice
  • Implicit and factual comprehension
  • Embed concept material in tasks

What is Mastery

  • He talked about what he called the ‘Cognitive Spiral’
  • Learning is a spiral that represents a time of opportunity and time to practice
  • From starting out as a beginner to becoming a master user
    • Retrieve explicit information
    • Interpret explicit information
    • Apply and use the information
    • Reflect on and evaluate the content.  This is where the users can be a big help to us with real feedback
    • Reflect on and evaluate the form of the message
  • These are really expert users
  • He defined Good UA as:
    • Give people the tools to get themselves out of trouble
    • Appeal to emotions and self-satisfaction
    • Crowd source the pain points.  Get the info from the user
    • Collect and analyze failure because if you don’t the social world will.  He used Dell computer as an example
    • Remember that failure is a learning experience.  Fail early and fail often
  • FAQ are solutions in search of a problem.
  • Let’s not insult our users by documenting very basic tasks.

STC Conference Notes from Tuesday May 20th

Here are my notes from Tuesday.

8:30-9:15 Designing Effective User Interface Content – Karen Scipi and Georgia Price Both Karen and Georgia are Language designers(?) for Oracle.   They work with SWD and UX designers to come up with the proper terms and phrases for various products at Oracle.  They talked a lot about being a Language Designer but I’m still not sure what that is. This session was pretty well attended.  The presentation and the slides were good.

  • Good UI will focus on all 3 design aspects, content.
  • Best UI text is clear, short and meaningful.
  • Identify what we can do in the SWD phase
  • Choose precise words and not specialized terms
  • Maintaining terms is very important for consistent messaging and helps to keep translation costs down.
  • Keeps voice and tone consistent.
  • Enables SEO
  • Language, voice and tone must be accurate.
  • Example – Error message, state the error and then the resolution.

9:45-10:30 Content Authoring for Responsive Design – Mike Hamilton Mike is a physics geek.  He worked for a nuclear power plant for several years working on process docs before he decided that it was not for him.  He went to work for BlueSky software after that and is currently working for MadCap.  This was a good presentation.  Lots of good information.

  • Responsive design is a design concept to address stress points, now known as break points in a browser.
  • Ethan Marcotte wrote a white paper on it
  • Responsive Design is not:
    • Making content size smaller to fit the smaller device.
    • Removing content to fit the smaller device
    • A separate version of the same content or every device.
  • Responsive Design is:
    • A single version of the content that formats correctly for all devices, phones, tablets, laptops, and larger screens.
  • The design principles are much more forgiving with Responsive Design, a much looser design is used.
  • The three key areas for Responsive Design are:
    • Document structure
    • CSS3
    • Media Queries
  • In RD less is more, don’t get too fancy at the authoring phase.
  • Hidden tables are bad,  fix size div’s fixed size images, all bad.  No inline formatting.
  • All of the style is done externally via CSS.
  • Couple examples of media queries:
    • @media screen for screen viewing
    • @media print for printing a page

He has some code examples that are simple but pretty good.  I need to get the slides.

  • Media queries can test for screen width/height, screen orientation landscape/portrait, aspect ratio, resolution and a few others.
  • Media queries works best with Chrome, firefox and safari.  Not so well with older versions of IE
  • Focus on content areas and purpose.  Don’t get caught up in the design for the page.
  • Control grid elements using CSS.
  • There are over 31 different device resolutions.  Chasing devices is hard to do.
  • Easier is to determine the min and max that you want to support.  With these end points in mind resize your browser and watch what happens, when things start to get ugly that will determine your first break point.  Continue resizing your browser until it gets ugly again.  That will be your second break point or the break point for a cell phone.
  • Graphics are harder to deal with then text
  • Larger graphics need to be split up in to smaller individual graphics and controlled with CSS.
  • Google search on responsive design.  Lots of information out there
  • To implement this is a pretty big effort.  Not something that can be done quickly.
  • DIV element is used a lot in Responsive Design

Small code sample:

div.rdoverflow {

overflow: auto; (if the content does not fit you will get horizontal scrollbar. )


1:00-1:45 Structured Authoring Meets Responsive Design – Mark Giffin Mark is a tech writer and picked up programming along the way.  DITA is a specialty of his. Not very well attended and only a small amount of information.

  • Structured authoring has been around for a long time and is being talked about more and more along with Responsive Design
  • Structured authoring and responsive can be a powerful combination.
  • Modern age of documentation is a mess.
  • Lots of ways to author
  • Lots of ways to publish
  • Lots of devices to service.
  • Content must be structured to be able to take advantage of Responsive Design

2:15-3:00 Basic Accessibility Tools and Techniques – Joseph O’Conner works for Knowbility Joseph was a fill in for Sharron Rush who was supposed to give the presentation.   He talked a lot about screen readers. I was hoping to get more information on color standards but the entire presentation was around screen readers.

His website is

  • Need to have a solid standard to test by, this includes all of the different browsers
  • WCAG 2.0 level AA Is a testing standard.
  • Test are all done in several different browsers, Chrome, FireFox, Safari
  • Use color checker for color contrast issues

  • Heading levels are important to people using a screen reader.
  • 70% of blind population is unemployed.
  • Enterprise tools will only test about 30% of all of the accessibility testing points
  • Document your findings
  • P.O.U.R
    • Perceivable
    • Operable
    • Understandable
    • Robust
  • Make sure you don’t have a dependency on color – ‘Click the red button’ for example
  • Testing should be a part of the overall TD or QA functions.
  • Look at for a list of accessibility tools

He finished his presentation with a couple of demos of various screen readers.

4:15-5:00 DITA is a Writers Best Friend – Ted Kuster Ted has worked at Salesforce for a couple of years. He has been a tech writer for about 15 years.  This was a good presentation.  Pretty short and basic content but the presentation was good.

  • DITA is an XML framework for technical documentation
  • DITA supports good writing practice
  • DITA is designed for writers
  • Saves you time
  • DITA and XML does not have a steep learning curve.
  • Ted feels he is a better writer now with DITA
  • Why DITA
    • ROI – Managers
    • Production – Engineers
    • Authoring – Writers
  • Writers do 3 things
    • Distill information
    • Assemble information
    • and deliver the information
  • Using the <shortdesc> tag consistently in every topic gave much better search results for Salesforce content.
  • 75% of what Salesforce does is instructional content
  • write a <shotrdesc> for every topic
  • use titles and <shotrdesc> in maps to boost search results

STC Conference Notes from Monday May 19th

Hi All,

My name is Allen and I work for Autodesk in San Francisco. I attended the STC Conference held in Phoenix AZ May 18th – 21st. It was a great conference with lots of good information. I thought I’d share my notes from the sessions I attended.

Monday May 19th 8:30-9:15 Content Designed for your Audience– Laura Creekmore This was a very good session.  Laura was a good speaker with a lot of good information.

  • Don’t let people get away with making changes to the content based on gut feeling.
  • Talking to your users is the biggest and best thing you can do.  You must know your user.

From here she had an interesting set of slides where she was showing how we have gone away from really knowing our customers/users back in the late 1800’s to today.  How we went from a general store where the store owner knew everyone that came in on a personal bases and could give them that same personal service.  To the first self-serve grocery store, to today where we can by things online and never have to talk to anyone. The companies that do the best with this are the large companies that spent the time up front to really know there customer.

  • We like to measure what’s easy.  Facebook likes, traffic data, YouTube view and comments and so on.
  • Web analytics tell you what, but what we really want to know is why.  Imperfect measure that only tells so much.
  • Use personas from UX data.  You need to use research to gather persona data.  You can’t just sit down and write a persona.  It will be as bad as not knowing anything if you don’t take the information from the user.
  • The best thing is to just get out and talk to your customers.
  • Be careful of putting too much weight behind surveys.  It’s too easy to write a survey with leading questions.
  • Focus groups are not a good way to come up with new ideas.  Hard to keep a focus group focused.
  • Sales and marketing data is sometimes very useful.
  • Product content needs to come from usability and analytics.
  • What is the actual content business goal.  You need to serve the business needs.  If the content is just in the way and is not serving a purpose, get rid of it.
  • Short quick sentences.
  • Every day we use phrases that are customers don’t understand.  Need to get the search data so we can see what the users are typing in to search.
  • An interesting test is to remove every 5th or 6th word and see if the user can fill in the blanks.  If the user can fill in over 60% of the blanks the content is pretty easy to reads.

Book Recommendations:

  • The user is always right – Good detail on how to write personas
  • Letting go of the words – Another great book for personas.
  • Content strategy at work
  • Interviewing users
  • Search and analytics
  • How to measure anything

Website Recommendations:

  • Reading level tests  Can copy content in and it will tell you what grade level you are writing to.
  • The Audience you didn’t know you had. (I need to get the links from the slides.)

9:45-10:30 Targeting Documentation to Your Users Goals – Alyssa Fox The slides were great for this presentation.  I need to get the link when they are posted.  This was another good presentation that was well attended.

  • UX and content go hand in hand.  If UX is bad the content will suffer and not be as good as it should be.
  • Need to really understand the user.  (This is a theme I’m seeing)
  • We really need to push back on SWD about bad UI.  We know UI is bad but just tell them how to use It in the docs.
  • Shrinking headcount means you really need to prioritize what we can get done.
  • Documentation must have context.
  • Traditional was to document everything.  Targeted documentation requires a solid knowledge of your user.
  • For targeted documentation only provide content for what’s really needed or required.  If it is a basic element in the UI like name, address and so on it does not require documentation.  Big picture tasks only.
  • Documentation based on persona is better than documenting only the UI.  From the UI you will only document the product and not how it will help the user or how the user uses your product.
  • Adding FAQ’s or troubling shooting topics are a big help.
  • Don’t waste your time documenting intuitive UI.
  • Start with the minimum information your users need.  Assume the user has some amount of knowledge.
  • Keep in mind that you are not the user.  You don’t use the product like the user does.

Book Recommendations:

  • Usability testing is key rocket surgery made easy – book for testing.

1:00-1:45 Key Trends in Mobile Publishing – Vikram Verma   Vikram works for Adobe as a product manager and was really pushing Adobe products. Had a small number of people in attendance.

  • Sense the iPhone everything has changed for the mobile device.
  • 1 out of every 6 people has a smart phone.  In Europe it is more than 50% of people
  • Late 2013 more people are getting content from a smart phone then on a laptop
  • HTML5 is the most dominant publishing output
  • For mobile use bigger buttons and remember needs to be designed for touch and not mouse input.
  • Design for responsive html.  When the device changes the page should change as well.
  • Users will abandon your content if it is not displayed correctly on a mobile device.
  • Consider a m. url for mobile docs
  • Consider creating a mobile app for your content
  • RESS (Responsive Server Side) is a hybrid of Responsive design and server side components.
  • RESS only has one domain.
  • But optimizing for mobile users with an app is the best way to go about it.  Issues are you have to manage two source content.  Updating app can be a challenge to keep up to date.
  • SEO is best when used with a domain or website.  Getting information on your user is easier with a website.

2:15-3:00 Delivering Technical Content to Mobile Devices – Matt Sullivan  Is an independent contractor that works for Adobe. He is using Framemaker and RoboHelp.

  • Content must be granular and structured for a mobile device.
  • Must establish the user needs first.  Then the tools to use will become more obvious.
  • Responsive output.
  • Responsive content gets placed higher when searched from a mobile device then none responsive.

3:30-4:15 What do Viewers of Video Really Want? – Matthew Pierce   This was a great presentation.  Good attendance and good information. He is with TechSmith and is working on , Camtasia, SnagIt and so on.  He is an industrial designer.  Then he moved in to a management role working with the training department then Tech Support.  Now he is running the video team.  (They have a good video library)

  • He thinks of video from a tech marketing position and learning.
  • It’s important to look at your audience for video.  Do your own research.
  • He feels video will be more accessible for people to consume and easier for people to create.
  • He surveyed 1900 people about videos.  Asked to send videos they thought were really good with more of a focus on Information and instructional.
  • Half of the videos from the survey were videos of entertainment.  Other half were Information and instructional.
  • Of the 1900 people they had a really good cross section of age groups from 15 to 75+
  • He feels video views will be increasing.  (But to me he is only looking at it from a delivery point of view and not from a user point of view.  Did not really get in to how useful videos are just that more people are watching them.)
  • Information and instructional videos are watched in the morning and in the evening when they get home mostly on their own time.
  • Length of video depends on type.  Their research is showing that longer videos are ok if the content is high quality and it keeps the user attention.  This is a length of 3 to 5 mins.
  • Video is an investment in time.  High cognitive load.
  • 82% of people will stop a video if it is not of interest to them.  (He feels this is really 100%)
  • People stop watching because, not the expected information, had other things to do, wrong topic, bored and bad content, bad audio.
  • Can’t skim videos like you can text, hard to scrub, can’t search on a specific section of the video.
  • Audio is just as important.  Good clear voice, good tone.  You can move pretty quick through a video as long as the content is clear and you are not trying to give the user too much information.
  • Things that make for great video attributes.  Trusted Brand, Callout text or closed caption, video with speakers for introduction, Music.  Music may not be appropriate for Information and instructional
  • People like things that move, intros and outros, allow comments in your videos.  YouTube is good for this.
  • Quality of video for Information and instructional means a lot.  People will just turn it off if it is not a good quality video.
  • Engagement starts with good story and script, good models, good video quality.

June Meeting: Ageism and Today’s Technical Communicator.

Ageism and Today’s Technical Communicator

Join us on Tuesday, June 10, 2014  for a lively evening discussing ageism in the field of technical communication.  Hiring managers and older candidates often experience frustration that is related to ageism and generational differences. Andrew Davis, a recruiter of technology industry content developers (Technical Writers, Trainers, and professionals with related skills), sees these issues first-hand and helps his candidates resolve them. In this presentation he’ll identify symptoms, causes, and solutions, all while seeking your input. Come prepared to participate; it’s sure to be a lively meeting.

Andrew Davis

Andrew Davis has recruited technical content developers in the SF Bay Area since 1995. He is a former software industry Technical Writer and has a reputation for both understanding and championing the role of content development.

Andrew enjoys helping those who communicate complex information get ahead by recognizing and refining their value to technology companies. He’s candid and connected and, just as importantly, he likes to help tech industry workers achieve their goals and achieve independence from intermediaries.

Andrew ran Synergistech Communications during the Internet Gold Rush years and has recently returned to solo recruiting mode. He remains focused on recruiting great technical content development talent for discerning local technology companies. Join him on LinkedIn ( to learn more.

May Meeting: Agile and Techcomm

Join us Tuesday, May 13, 2014 for an educational evening of opinions and well, more opinions on the subject of Agile and Techcomm (roundtable-debate).

We have three knowledgeable people who will present various sides to this story, Shelley Horwitz, Mike Ziegenhagen, and Mark Weddle. After a short presentation from each, we’ll go into roundtable mode and discuss the pros/cons among the group.

Here’s Wikipedia’s entry on Agile Software Development.

If you are unable to join us in person, we plan to offer remote attendance via GoToMeeting (possibly audio-only).

Info from Meeting

You’ll hear lots of opinions from the group on the recording .. if you have opinions you’d like to share, please post them as comments below!