Writers and Product Usability
- All writers are (or should be) involved in product usability
- Hardware as well as software, APIs as well as GUIs
- We’re the canary in the coal mine (we suffer first)
- When it’s hard to explain, it’s hard to use — and docs won’t help
- We’re more tuned to consistency than most
- When we create examples, we notice gaps in the functionality matrix
- We can identify “dovetailing issues”
- When we can help to create a more usable product
- We need to speak more, speak louder, and learn how to make our case better
Scribe: Gayle Naylor
- This is hard!
- Many challenges are a result of organization issues
- Tech writers need more power, AKA better visibility
- Things that can help: develop good personas for usability testing, get buy-in, look for allies
- Choose your battles and celebrate your successes!
- Big Questions: How do you get taken seriously and how do you build your visibility in the organization? You need to be visible and taken seriously so you can bring to light issues that will be acted upon.
- Challenges: Tech writers are low on the power spectrum. Engineers often do not have a good view of the audience and are unable to put themselves in the audience’s shoes. Engineers are also very focused and want to make a perfect system. Not big on considering the big picture or consistency.
- Usability testing challenges may be more than one type of user (novice vs experienced)
- Should tech writers be involved in usability testing? Sometimes you have to if you are in a small organization
- Resource: Steve Krug “Don’t Make Me Think” and “Rocket Surgery Made Easy”
- Design environment challenges: Do you see the design before it is implemented? Does not help if you point out issue when it is too late (Timing is everything)
- In Agile environments, no longer have design docs which makes having an impact early enough in the design difficult. Often there are not enough tech writers to attend every scrum stand up.
- Terminology control is a challenge. (Also concept control. There should be a 1:1 relationship between terms and concepts). Hard/impossible to standardize terms because too many different groups with different requirements (e.g. marketing, sales engineers, etc). Also, sometimes there are legacy code issues that perpetuate old terminology
- Things you can do: Show visibility issues – show engineers an example of a real use having issues. Program managers often assume engineers know more than they do – helps if you can orient proj. mgr. to the issues.
- Need to carefully select the people who test.
- Creating personas is a good idea. Having detailed personals can really help the discussion be productive and help you make your point. Need to research the personas, make sure they are grounded in real data – go out and talk to real people. Try logic: “I could spend 3 weeks making the product understandable or the developer could spend 3 days fixing the issue once and for all” “Wouldn’t it be easier to spend $5 on usability now rather than $500 in 3 years after we have lost 50% of our user base?”
- Change the organization from below. Sometimes leading from below works, sometimes not. Need to cultivate allies. If possible, try to get early input on design. Really need to demon designs so they can be criticized at the beginning rather than have people criticize at the end of the process when it is too late.
- Challenges and tools to automate publishing in multiple formats
- Planning and adjusting
Scribe: Liz Miller
- Start manually – make macros to ease the pain of repetitive tasks
- Document the painful steps for management/business case/roi
- Wade through many tools to automate steps/scripting (from DITA to PDF, for example)
- Seek a cheaper tool to automate checks for readability, broken links, etc
- Continuous integration (Jenkins)
- DITA-based reference docs for each customer in downloadable zip files
- script used to unwrap DITA files (Maven)
- configuration file in XML to coordinate job
- Jenkins workflow set up in house by experts – Project Object Model (POM) files
- Automatic generated Release Notes in synch with product builds (Jira/Bugzilla)
- Confluence wiki
- Bamboo for build process integration server
- Output was build script but can create deployables
- Alfresco – custom workflows where approvals generate DITA doc outputs (PDF, HTML, ePub), an XML transformation for product delivery
- Opportunity for doc automation
- Intel tech pubs team mostly PDF from Hardware docs; developers are the content developers too (the engineers); management decision.
- Chevron – old school – Sharepoint/MS Office tools. Revising product doc library files
- PLM (product lifecycle management) tool vs customers engineers who duplicated (Windchill)
- XSL->DITA->Content repository updates for current PDF rendering. How to preserve document look and feel while automating processes to deliver? Consider updating for tools ability
- Another definition of document automation — local personal macros. Fix pain points of manual tasks wherever you can
- Opportunity to adopt and adjust as getting started. Publishing DITA content process needed; researching now. Recommended: Do it manually first. Nail down the steps and tweak before adopting automation. List the steps for ROI business case to get management to fund the tool. Pilot may reveal not feasible; script may not be doable if human judgement needed for completion.
- Automated readability tools – for non english engineer authors. basic function = # of sentences, words/sentence, etc. Could be automated.
- Acrolinx based on basic business language & customized for enterprise/organization. Is it worth the cost?
- Schematron/HyperSTE/Prince XML/Simplified Technical English. Seeking a cheaper tool for automating readability, finding broken links, intelligent checking
- Your favorite tools: FrameMaker, Arbortext, Author-It, XMetaL, SDL, Word, Sharepoint, RoboHelp, MadCap, wikis, etc
Scribe: Todd Lewandowski
- We like the tools that are small, easy, and transparent
- Only a small group of tools to remain productive
- DITA & open source standards are Super Important in the future, especially for localization. Reduces major headaches
- Namedrop – Google Docs, Snagit, School Loop, Google Drawings & Lucid Chants
- DITA Generator for easy creation of templates (75% of most cases)
- Creating simple documents – FrameMaker (for DITA), Word (for standalone)
- Word vs Google Docs – some companies open; some still security restricted
- School Loop for websites (school districts)
- epubs for immediate consumption (construction, science labs, medical, flight attendants)
- DITA mainly is for content reuse and localization
- Need a small transparent tool. Small subgroup that is effective. gdocs, frame/adobe, PDFs manual. DITA (any vendor) is input for long term reuse, especially translation.
- Stick to open source formats to keep options for future
- Different translation vendors for different languages
- DITA generator – make templates for DITA
Reuse Strategies: Thinking Like an Information Architect
- Keeping a handle on your reuse
- reuse strategies
- Thinking like an information architect
- How to find reuse
- Planning reuse and tracking it across your documentation set
- How to Author for reuse
- Authoring to different formats – re-author, just reuse, audience analysis, pluses and minuses
Scribe: Kristen Toole & Karl Lasebrink
- Basic questions: what does an IA do?
- Thought process: Identify how customers use and consume content at beginning of sprint
- 2 reuse strategies: (1) just start with content, make it searchable by authors (2) read only library
- IA controls the shop
- Strategy (for link management) and governance are most important. Tools should tell you where content is reused. Use “show reuse”
- Just because something can be reused doesn’t mean it should be reused!
- Content strategists build ecosystem
- Think about information access points, metadata, taxonomies (varies by shop)
- task/reference (DITA) model – can do it w/o DITA
- IA puts your content into the build or DITAmap
- In mature DITA shops they create content maps, lots of content readability available
- Question: Content reuse within topic – “wrong” to use conrefs?
- Base governance that allows collaboration should help in merges and company splits.
- Content Audit helps understand how content is used. Change happens fast so use Agile model, (incremental). Can be useful to justify CMS. Show overlap, e.g., value to convert to DITA, make use of frame files for publishing to multiple versions
- Unstructured frame migration to DITA – semantic markup, especially used for matching tasks.
- DITA 1.3 has troubleshooting “decision tree”
- DITA is formalized method for information typing.
- Moving content is easier if you have already chunked content. Write with discipline!
- Unstructured -> structured -> XML/DITA semantic markup rules for writing DITA allows automation
- IBM style guide available on Safari Books.
- If chunk of content works in one context then how can you be sure it’s successful in another context? Google analytics is a big help. Track support metrics, understand how users use content
- It’s good to write first, organize later. Necessary in an Agile environment – no outline.
- Single source vs copy/paste (change in 2 places)
- Tags are limited by structured application (FrameMaker, Webworks, Acrobat pro tools are sufficient for an IA)
- Need to migrate to new CMS – tag usage should be driven by business case
- Reuse of unstructured content is doable. Keep tasks distinct and independent.
- Never hyperlink to another topic – with exception
- Use keys not links – depends on user group, clusters of links help with that.
- Things go bad when you reuse topics. Relationship tables are useful in map not in content.
- Titles should be descriptive or have pop-up
- Topics must be within context – links – conditional topics less bulky for mobile.
- Visual presentations
- Writing content that isn’t tetx
Scribe: Tonie Flores
- Advantage over text, where to use them
- Mindset to think visually – how to train ourselves
- Learning tools – canvas, ragan.com, Ikea, airplane exit instructions, Legos, Tufte
- How to collaborate w/artists and UX – we bring technology
- Global awareness, pictures are not universal. e.g., Tide commercial – left to right vs right to left
- There are video infographics.
- Permutations- still, interactive, no words at all
- USAToday – pictures & captions
- Economics – The optimal length of social media. the internet is a zoo
- Nice inforgraphics
- Not just quick info – more memorable for retention
- Not just chart junk
- Font size is a component of infographic
- People stay on page longer on web site or paper if it has pictures.
- Pictures as a reward – like badges
- Can create infographic with web apps (canvas)
- What is an infographic vs regular graphics – Integrated words and graphics
- visual representation of data
- Tufte – Lundon places; Napoleon – multivariate vs chart junk
- Looked at Wikipedia definition
- Google search comes up with lots of PG&E
- Uses symbology – or analogy for abstract concept – like turtles or ice cream, ear of corn representative of food prices
- Is there enough data in user guide/admin guide to justify cost of infographics?
- Infographics easy to digest
- Graphic to show inter relation of a suite of products; tool for selling techpubs as a revenue generator.
- PPT? Not one series of slides
- Fuzzy line – graphics vs infographics
- Infographics tell a story. Can stand alone
- Plain graphics need support of surrounding words – modern day poster
- Epidemic graphic showed it came from the well (Ted Talk)
- Ikea – an infographic? Not really, not one picture – insets for quick start.
- Uses fundamentals like shapes we know
- How to visualize concepts, not just information – ragan.com course on infographics
- What lends itself day to day. Use of documentation by infographics?
- We’re not trained as artists. What if at start of every project you doodled or used Visio to do a graphic? You’ll get better at it. Practice, Kid, Practice!
- Accessibility – can’t have visual only, must be readable by voice reader – use metadata.
- Professional note taker at corporate meeting did ti all with graphics. Figures, arrows, etc. Didn’t know anything about the company or product.
- Tech writer & UX work together might bring it together. Teamwork with artist. We bring technical, localization considerations. Lots of synergy. We can contribute to usability
- Urine infographics at doctor’s office – 4 glasses of beer, light to dark..
- Where to use? High level concepts, executives, analytics. Web for short attention span.
- Changing used to be “above the fold” now scrolling is OK
Document Review Processes
- Document review process
- Our authoring tools have evolved but a lot of us are still doing technical reviews the way we used to 10 years ago
- How can we improve the tools process?
Scribe: Pete Dakota
- A solution has to allow reviewers to see each other’s comments.
- Keys to good reviews: (1) set expectations and (2) send out appropriate size reviews (no 500-pg docs)
- PDF and Word still the big favorites among companies
- Non-tech writers comfortable with it – don’t want to use new tools/processes.
- Biggest challenges are cultural/people, not necessarily technology
- Typical review team size 3-5
- “Impossible solutions” oxygen web-help with comments. DITA to Word transition
- Handle it like a code review
- Create user stories for reviews in agile environment, then it’s part of the schedule (also needs to come from upper management)
- Doc reviewing is part of SME job description – part of annual performance review
- it’s a big problem, cultural & technology