Session 2 Summaries – 24 January 2015

Session 2 Topics For Discussion

Improving Search

Scribe: Rita Tharakan

Top Takeaways:

  • Using a non-standard search tool – the importance of using an indexer’s mentality to get around the search problem and it’s limitations
  • Write for retrieval
  • In web based searches with standard tools, leveraging tools like Google Analytics or Amazon history to test searches with dummy pages


Linguistic algorithms

Searches can be too broad

Searches are content-dependent. Very clever searches out there

Metadata and keywords to expand search

Ctrl-F and PDFs vs how much you lose when you cut it up into topics. Whole doc search vs page

Use an old-fashioned index

Google analytics

Breadcrumbs for topic-based pages to test searches – to see context

In-built limitations of proprietary search engines built into tools. Index used to cover search inadequacies

Document alternative terms, marketing terminology

Personalized searches and privacy

Educating user about search tips, wildcards, expression. Search training. Show examples. Make regex part of high school training

Personalities – narrow search by using an explicit profile form up front. Faceted search

Voice search – accents

Writing for retrieval

Mentality of the indexer into search

Role of Information Architects in Info Design

Scribe: Rebecca Firestone/Bonnie Kim

Top Takeaways:

  • Roles, responsibilities. What does an IA do?
  • IA still looks at audience, needs, delivery, but then also reuse strategies, conditionalizing, topic organization
  • Scaling up, when do you need to hire an IA? Sometimes it’s a role or partial role
  • Diff between IA (big picture) vs TW (accurate details)
  • How will web pages look? Context for non-sequential access. where to go next?
  • Top-down and bottom up learning styles
  • IA is continuous process, a 2-way street, especially with multiple authors
  • IAs don’t necessarily do tool implementation


How many IAs on DITA?

Do you have to use DITA to be an IA? No

In DITA IA is superimposed on top of DITA, but DITA is not all the IA does

IA still looks at : What info do they want? where to find/access? format? audience?

After defining content, implementing (1) reuse strategies (2) conditionalizing strategies (3) how topics set up in CMS

What do you need to add an IA? Team size? Scale? Every TW needs IA skills. Role is not necessarily entire job description

IA: Look how content fits in bigger picture

TW: Look at details, accurate – understand audience, understand tasks, organize content accordingly

IA can mean a lot of things. Do they need to know tools & how to implement?

When can a TW claim skill as an IA?

When to split out IA role as separate?

Plan authoring in distributed model, multiple authors in different locations

IA during corporate acquisitions and consolidation

topic-based doesn’t mean short topics only

Need an author to exercise good judgment

Who should dictate content? Info dev or product managers?

Moving to HTML means – no way to enforce order of access. user can read in any order; Providing context in non-sequential access

Some need for holistic approach – avoid things like “it” or “below”; reader used to get context from doc/TOC. “Installing Product A” use descriptive topic or Metadata?

Old school: TOC = sequential. Print (TOC, C, IX) -> Web (c) also need TOC and glossary but not for sequencing

How will web pages look? How will pages be served, assembled?

Integrate TOC with search results. Example: API (TOC = API call); No API = Task. Title=command (advanced); subtitle (prose description, novice)

When somebody lands on page, where do they go next? Links, structure, toc,…  — what are clues for what else is available? e.g., drop downs, filters, see also, concept, instructions.

You can concatenate concept + instructions & show to user as one page

Landing page: immediate question. Next? Parent, child, sibling

Learning styles differ – some are linear, some are chunked or asynchronous. Top-down and bottom up.

Content per print page: extracted from longer book – what about writing in a distributed model?

max # of cliches?

IA is a continuous process

IA is a 2-way street

IA vs tool architecture

IAs (role) don’t necessarily specify tools or do implementation


Scribe:  Matt Ness

Top Takeaways:

  • Encourage Management to recognize overlap between UX and User Assistance
  • Show them results of your own testing
  • Clearly present problem and offer solution
  • You may uncover hidden costs!
  • Test, iterate, test, iterate
  • Enter usability problems into bug tracking system
  • Convince PM/Dev you know what you’re talking about
  • Be courteously persistent
  • More UX w/mobile
  • Tech writers and UX in agile are a sprint ahead of developers


Writers should be involved in product usability: “When it is hard to write about, it’s hard to use”

Products where the documentation is trying to solve for deficiencies in the UI: “They are so involved w/product, they can’t relate to the user”

XML issues where one person goes to many sources

Companies where writers are highly involved with UX

When designers do not make intuitive products

Huge amount of overlap between user assistance and UX

ESL issues gets involved with usability

UX designers who eschew UA in favor of spare, minimalist, text-free designs: some writers have better luck forging partnerships with UI/UX

Usability tested installation guide – invited dev lead (who never looked at docs) – they could not complete installation b/c of bad UI: Message would tell you to do something that caused installation to fail.

Classic mention of door usability: doors you push when you should be pulling

Usability testing, documentation: often not enough. “We’ve done scrappy testing at coffee shops”

Perspective from developer can see the usability issues from the other side

Testing doc usability by monitoring doc usage and responding to feedback (wiki-based docs)

Usability dovetails with accessibility: content reuse (reduces translation costs); doing usability up front did a lot of writing. Best case: Intuit’s “follow home” testing. Worst case: UX design for government projects

Wrangling Difficult Personalities

Scribe: Unknown

Top Takeaways:

  • Difficult Problems: People who are psychopaths, egotistical, keeps silence, insecure, manipulative, shy, indecisive.
  • Other problems: Cultural problems, organizational problems, and gender problems
  • Solutions: Don’t be aggressive and be assertive; treat people like a human being; get support from professional; reflect on their understanding; be open; be flexible; understand that you don’t have to agree with them; tailor your communication
  • Books Recommended: “Snakes and Suits” , “Psychopaths Next Door”, “Assholes: A theory”


Good day: Didn’t kill the Engineer

Solution: Aggressive won’t work; Assertive will. “I” statements not “You” statements. Name the game and not get fired.

Books: “Snakes and Suits” , “Psychopaths Next Door”

Talk it out. Try not to offend. Speak slower. Get support; faking incompetence. Clarify what you do in your job

Problem: Getting info from people; convoluted response; egotistical workers; organization that tolerates problems; psychopathic personals; empathy never works at time; manipulative, insecure

Try to get info and they try to run away; additional relationship to get support

Put yourself in other person’s shoes

Try to get “some authority”

Treat other person as human being (not a monster or a brat)

good intention

Book: “Asshole, a theory”

There is no ideal

Openness, flexibility, good sense of humor

Understand them, you don’t have to agree with them

Human resources is working for the company

Open door policy – go to your boss’s boss

Reflect what they “really” mean – context

Tailor your communication

Bribe with food

The one who things this world belongs to them

“Come back with a solution” (boss)

Shy people who won’t speak up

Indecisive (“I prefer not to”)

Wrangler: Takes care of horses

cultural problems

Reuse Strategies

Scribe: Robin Whitmore

Top Takeaways:

  • How to Reuse Successfully
  • Need to make content findable
  • Need to have rules – notification when content changes: Communication is key
  • Use tools – small spreadsheets, ccms -where used, frame text insets, resource files (for paragraph level or lower), comments, conditional text
  • Does size matter? Granular = more reusable
  • Linking makes it difficult


Issues with finding content? All depts need to be able to access and use same terminology

Granularity is important? How granular?

Can also be multi-channel

Tools recommendation – use spreadsheets. Can use “where used” or other function in CCMS. Wikis that describe content. Comments in content – about what context is for and who is using it. Need to communicate when changing content. Can use conditional text for differences.

Helps to have “content captains” who own content areas and are aware of where content is used

Does size matter? Topic vs Phrase. Genericize more than in the past – writing for reuse. Create one topic (generic) for description that can be reused

Text insets in Frame? Could use for standardized procedures, copyright.

IBM has vision of allowing writer to begin writing & the GUI will tell them that the content already exists.

Only reuse “released” topics

Have version-specific comments for release info

Training  and Techpubs: Pair writer with trainer. Reuse portions together. Trainers come up with the content, this has smoothed things out

Doc Workflows based on Markdown and Git

Scribe: Steve Anderson

Top Takeaways:

  • MD=Lightweight markup language, typically converted to HTML
  • Git=DVCS – distributed version control system, focuses on branch model
  • github makes it easy to use markdown
  • git – your local copy is a complete copy
  • workflow – sync with master, create branch, make changes, commit, create pull request, merge to master
  • how do you handle conflicts? there’s no file logging. Depends on model: push (last push has to resolve the conflict) or push (the “owner” handles the conflict)
  • binary files are not git’s strength
  • git workflow support example: DITA OT in git repo


Approximately 5 people using git and/or markdown

You can put HTML in Markdown

GIT has hooks : pre-commit and post-commit

Interchange, localization -> probably convert MD to HTML

Are there any vendors that support markdown?

MD=>HTML – what’s the Marker? In a L10N process, it might be good enough to treat MD as master, but HTML is the translated master.

We’re moving towards plain text – simple

Workflows:  authoring, review, publishing, translation


Language tool (aka Acrolinx) – Not available?

Requires an ecosystem

ADDITIONAL NOTES from Liz Fraley (transcriber): If you’re looking at Git, be sure to also look at Gerrit and Jenkins and this article: “Git from the Bottom Up” Cheers!