Session 2 Topics For Discussion
- Improving Search
- Role of Information Architects in Info Design
- Wrangling Difficult Personalities
- Reuse strategies
- Doc Workflows based on Markdown and Git
Scribe: Rita Tharakan
- 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
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
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
- 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
- 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
- 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)
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
Scribe: Robin Whitmore
- 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
- 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
GIT vs CMS
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!