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!

Session 1 Summaries – 24 January 2015

Session 1 Topics For Discussion

1. Documenting APIs

Scribe: Karen Aidi

Facilitator: Fred Jacobson

Top Takeaways:

  • Knowing a programming language is virtually essential (Start with Python or an easy lang)
  • Know the industry and the domain language to communicate effectively
  • Look at Web APIs – particularly REST APIs – look at Twitter and Flickr APIs as documentation models
  • Using your language write a small code snippet
  • Account for the range of experience of your audience


Fred started out with asking what the participants wanted to get out of the session. Most were interested in how to break into API technical writing. There were many themes and questions throughout this session:

  • What is API documentation?
  • What is good API documentation?
  • Do I have to be a programmer to write API documentation?
  • Who writes the code samples?
  • What is the difference between a human writing the API documentation versus “autodoc” reference manuals?
  • How do I get started as an API writer?

There was a general acknowledgement that there are many API writing jobs. And, these jobs want a person to know several programming languages: such as Java, JavaScript, PHP, C++, Python, just to name a few. A lot of job descriptions seem to reference REST APIs, so those seem to be very much in demand right now.

What is API documentation?

There were both newcomers to documenting APIs as well as experienced API writers in the group. Newcomers to documenting APIs, asked for a brief definition of what an API is. An API defines how two pieces of software talk with each other. There are many types of APIs: APIs to extend an existing software system as well as Web APIs.

Sarah Maddox gave two examples of Web Service APIs: Flickr and Twitter. As an example, she mentioned that a WordPress blog uses the Twitter API when the blog includes a twitter feed on a web page.

A participant asked: does a (web) service mean the same as an API? No, it doesn’t. There are different types of APIs: web services APIs might be REST APIs or other APIs, while some APIs may extend an existing system by using a Java API.

What is good API documentation?

Tactics for producing good API documentation include: interviewing project managers, internal users, and other users besides just the engineers, and looking at marketing documentation to get an overview.

In an agile environment, look at the user stories, which will help the writer with use cases. Learn about the development process by observing engineering in your own company.

Do I have to be a programmer to write API documentation?

Do you need to be a programmer (coder) to write API documentation? Not necessarily, but writers should know what programming is, should learn a programming language, and experiment with code snippets themselves. Fred mentioned that a good programming language to start with is Python.

To get some practical experience, one participant recommended using Postman,

an extension to Chrome. You can go from Trjullio or Twitter and start making some calls with Postman.

Who writes the code samples?

Does the writer write code samples or does the programmer write them? Yes and no and it could depend on the job.

One writer shared that he has never had to actually write the code samples. Usually, he leverages code from QA. Another tactic might be for the writer to create a story to provide a context for the examples throughout the documentation.

Programmers want to get their job done, so they love code samples that they can use. In some cases, the programmers will write the code samples, particularly, the more involved code samples.

What is the difference between a human writing the API documentation versus “autodoc” reference manuals?

Automatically generated or “autodoc” reference manuals are automatically generated from the code source. The programmer may write the first cut descriptions. However, the human still needs to be involved because there is a gap between the reference manual and the task that a programmer needs to perform. This is where writers can add a great deal of value. Auto-generated reference manuals may be laden with jargon or may not explain terms or pre-requisite tasks that are useful to all levels in the target audience.

How do I get started as an API writer?

How does one go from government type of work to API documentation? The analogy given was a car analogy. If you are in the left lane and you want to move into the right lane, you signal that you want to make a lane change, and you start to steer yourself in that direction. Find an API that you like, write some code, build an example, and then publish. Learn one language, learn the principles. What language to learn? Python was mentioned by Fred as a language to start learning.

How does one deal with intellectual property (proprietary API) versus public APIs or REST APIs?

Understand the audience. Use conditional text to prepare two different deliverables: one for an internal audience and one for an external audience.

2. Scripting FrameMaker

Scribe: Joanna Broadbeck

Top Takeaways:

  • Scripting FrameMaker is used to automate repetitive task or tasks that must be performed across many files
  • There are two methods for scripting. ExtendScript is a Javascript-based language provided by Adobe and is free. FrameScript is a 3rd party solution more similar to VB Script
  • It isn’t easy to get started. There are several consultants available. See their websites, free samples


What is it?

MIF-save in this format to go to older version, to get rid of errors, “MIF washing”

ExtendScript (in FM12) vs FrameScript

Scripts can do all things you can do manually, via script

Rick Quattro does scripting

You must know FrameMaker document model; scripts can read external file

Scott does FDK development

Where’s the good documentation? Adobe FM Scriptmaking Guile

Developer Portal.

Sec West Street Consulting – FDK developer that created many samples

Resource: Adobe FrameMaker Scripting Guide

Inter-application communications are possible FM<–>other adobe products

Script types: Notification scripts, startup scripts, etc

What would you use it for?

  1. Doc conversion and apply templates (you can make a map for that)
  2. Use scripts for automated formatting (anything you can do manually)
  3. Create PDFs (lots of books)
  4. Carpal Tunnel prevention!
  5. Reduce the time it takes to do repetitive activities
  6. Huge search/replace
  7. Master books (including books within books) – website has plug-ins, including free
  8. Apply tags to many files
  9. Restructuring docs based on styles to go into DITA
  10. Assigning attributes to conditions during a conversion

How much need is there for scripting FrameMaker? It’s not difficult, but … West Street Consulting = Russ Ward does sessions on scripting in various languages; Scott Prentice – just spoke about going from FM to DITA

Semi-related discussion: Companies are using Word again. Easy to record a script. if developers must edit, companies use word.

ExtendScript only works on Adobe products – Not for MS products

Download samples form West Street Consultants, Frame Gurus, Adobe Forums

3. Keeping up with industry trends

Scribe: Wendy Shaffer

Top Takeaways:

  • Safari Books Online
  • Slideshare
  • Techwr-l list
  • Conferences
  • com
  • Code Academy


Self-teaching: safari books online

Slideshare is a great resource for presentations

industry trends: Writing style (Simplified Technical English), Mobile, Video, Social Media, Personalization, Pushing Marketing Language in Tech doc


Learn from your developers

Conferences (video tutorials)

Code academy (for python, html, others)

Blogs, news sites

4. HTML5

Scribe: Greg Urban

Top takeaways:

  • HTML4 compare to HTML5 (HTML 4+1)
  • new tags- a lot more tags
  • attributes – many more
  • cool features – audio tag, video tag, will pull in screen elements, including video player and IO player
  • advantages: no more div soup


HTML5: API, video tagging, looping video

new tag – Lots more – easier to understand

Recap of HTML development, interoperability usage of divs

HTML5 responsiveness depends on CSS, JavaScript

Data elements can move, flexible attributes not limited

efficient for video and audio tags

Advantages: no longer have to have a div

5. Metadata and categorization strategies

Scribe: Joan Lasselle

Top takeaways:

  • can be simple or highly complex
  • managed informally or managed by a specialist
  • Helpful to have specifically trained specialist to help you get started
  • Used to find topics/content (internal); use to help customer find data (external); use to track status of content


Link with library science

The Accidental Taxonomist – introductory book , IA Institute

Few using today

Each topic – pick from a list

hard to come to a decision about what metadata

What do you want it for – to find topics in future to manage customer experience

Determined by queries

Most use to manage topics internally

Should not be redundant with the content

Keyword metadata – how do keywords relate to SEO

Metadata then keywords

metadata categories

Taxonomy – Define the context, what is the set of data you are working

who for

why do it

6. Job search techniques

Scribe: Ryan Young

Top Takeaways:

  • Job boards – loud but low quality
  • LinkedIn – higher quality, more work
  • Referrals – highest quality, most work
  • Make your own job – a lot of work


Everyone in the job market

Job boards – loud but low quality – sponsored, there probably isn’t an 100$ fit for any job; the best fit is around 80%; sentient, articulate, fearless, and audience-aware

LinkedIn/Indexed/Simply Hired – higher quality, more work – costs $400 for 30-day to post a job, often just looking for future candidates (sometimes); listings != opportunity; better to know someone; LinkedIn is best – you know who is responding; “Post and pray”; LinkedIn is honest and refreshed often, others are dishonest or not trusted;

Referrals – highest quality, most work – companies like internal references better; most reliable and safest – internal referral bonuses are high;

Make your own job – a lot of work – find solutions to problems, consultants make more, even introverts can do it, and if not, get a “puppet” to be the face and voice

postings are “wish lists”

Ask people to prioritize job descriptions

Take job descriptions and create table comparing requirements to your skills

Teach yourself skills

Companies don’t post contract opportunities – once these go to an agency, the rate goes down

LinkedIn: use search + term – rich summaries and titles, use word cloud to get terms “writer” not “info developer”

Be forthcoming in summary about what you want to do to avoid marketing/social media jobs

Read job description that interest you: if you don’t have the skills, learn them. Start teaching yourself.

LinkSV: Search jobs by zip, search jobs here, contact companies via LinkedIn

Recruiters: self-interested sales people, who work for client – not you; won’t remember you; Short attention span: explain things to them using the job description. Tell them how much you need to earn.

Resumes need to clearly demonstrate how you map to job requirements. Needs to be clear why you are applying to this job

Project resumes sometimes seen as liabilities because they might be “mashs”

Employees want to see chronological resumes & escalating responsibilities

2-5 years/job is a good duration

Free conferences -> the trade show portion

Volunteer in tech writing organizations

Session Matrix – Saturday 24 January 2015

Morning Workshops

Any slides, pictures, video, links, and scribe notes are on the individual workshop pages. Sessions are listed in order of discussion table order.

Unconference Sessions

Session #1 Matrix – Scribe Notes

  1. Documenting APIs
  2. Scripting FrameMaker
  3. Keeping up with industry trends
  4. HTML5
  5. Metadata and categorization strategies
  6. Job search techniques, leveraging LinkedIn, recruiters, portfolios

Session #2 Matrix – Scribe Notes

  1. Improving search
  2. Role of Information Architect
  3. Writers and product usability
  4. Wrangling difficult personalities
  5. Reuse strategies
  6. Doc workflows based on Markdown and Git

Session #3 Matrix – Scribe Notes

  1. Generating PDF from DITA
  2. Teaching topic-oriented writing
  3. Mobile documentation
  4. Document review process
  5. Style Guides
  6. TC in an Agile envionment