My notes from the presentations on the second day of Write the Docs Portland 2023.
Caitlin Davey – The visuals your users never saw… wait that’s most of them
- draws on instructional design principles, specifically visuals
- ways to make images more cognitively interesting so they don’t just breeze past them without taking away the important points
- think of technical writing as directing attention towards information
- important to consider cognitive load, similar to info overload
- refers to how much info someone can process at a given time
- want people cognitive capacity for the core things we want them to take away and learn
- don’t gloss over visual, be cognizant of what we’re adding to docs
- reading info involves selecting, organizing, and integrating
- Seductive detail effect: entertaining bits of info or entertaining, reduces remembering key info, tend to remember them better, but not necessarily taking away key info
- interfere with steps in reading process
- can be extra text, images; distract from key learning
- shown to be damaging to problem solving ability
- don’t worry about emotional interest, focus on cognitive interest
- more interesting when learners understand,
- help readers form causal chain of events: connect text and illustrations to make sense of the cause and effect of topic
- material that promotes cognitives interest include highlighting key aspects
- Takeaway: Bad visual aren’t benign. They divert attention, can confuse key points.
- visual are worth it, don’t throw it out just because they’re hard
- encourage learners to engage in active learning and making connections between pictures and words
- use explanative illustrations to help learners process info
- 12 principles: coherence, signaling, redundancy, spatial contiguity, temporal contiguity, segmenting, multimedia, modality, pre-training, personalization, voice, image
- coherence: eliminate extraneous info
- don’t be afraid to break up visual, like breaking up text
- signaling used to highlight essential info, with text bullet points or visually
- Simplify and make explicit connections between info text and visual.
- Bad visuals interfere with learning’ s ability to build connections
- select visuals based on use case
- screenshot: useful for facts, specific form, screens, equipment; take advantage of coherence, signaling
- think about where you want users to take away critical takeaways
- for concepts, show examples and non-examples or analogies
- analogy examples: envelope for email, trash can
- process: show stages, motion use animated diagrams
- show step by step tables or demos
- still image can be better for recall, so make sure to think about still vs. animated
- can illustrate lots of info (facts, concepts, procedures) not just screens
- summary:
- bad visual aren’t benign
- simplify and make explicit connections between info text and visual
- you can communicate so much in visual, so take advantage of that
- be open to creativity in design and delivery of docs
- iterate and improve visuals as you gather more info
Q&A
- accessibility: a lot of tools to check for accessibility: contrast, gif can be difficult to process
- software that changes quickly and maintenance: wanted to get away from encouraging screenshot visuals, more you can visual tlike procedures, examples, non-examples, principles, core concepts; evergreen pieces of info you can add visual aspects to
- kind of deliverable change what visual to have: docs tend to rely on screenshots for visual explanations, encourage folks to consider if necessary. Are we just showing a button that can be shown by text, visualizing and simplifying different components of ino you’re sharing
- how to trim seductive details: think about things that you’re adding in that are funny or tangental. Visual should really be connected to the point you’re trying to drive home. Don’t try to drive emotional interest
- cognitive load work very difficulty for neurodivergents: all learners, working memory is limited, think about how much processing something can do is broadly applicable
- someone to remember based on location, desirable?: can be. good doc we do a lot of stuff in text that we do well. Want to translate that to visuals
Ed Cormany – The Descriptivist Manifesto
- you think you know a lot of English, then exposed to a lot of new terminology
- seen the pattern of English words, but at company, used the word ‘labware’ as count noun
- we describe patterns, not just rules
- colliquation: particular
- google ngram viewer: 2+ bill, results over time, visual sense of how different phrases are used over time
- usage in a smaller community: put on vs put in
- started in Figma design file: could search text. 31 vs. 36 results
- search in repositories: 14 vs. 81 files
- local copy: 16 vs. 349
- add to style guide
- Manifesto for documentarians:
- spoken language is unique human > We speak a lot when we create products.
- writing is a fundamental human tech > We write a lot when we create products.
- writing reflects speech, though writing is not speech > What we say and write reflects the product, but it’s not the product.
- observing how we communicate in speech informs how we communicate in writing > Talking about the product helps us calrify our writing about the product.
- communication is based in community > Listening to our teams builds understanding.
Document our products the same way we talk about our products
- listen to those conversations, participate in as many of them as you can
Q&A
- people see prescriptive and descriptivism, lot of tension between them, how do you let go of rigidity?: in linguists training allowed to let go. Was teaching courses, gave them freedom to express themselves. Just let them communicate.
- internal vs. external language, terminology; how does it apply when totally different for different audiences?: insular language community, tend to build jargon. Have to be vigilant about community addressing. What is the community that I’m addressing now? Number 1 is who is your audience? You can still make use of the expertise from the inside.
- isn’t descriptivism, why non-writers hate us?: that’s a tough connection to make. The pejorative way to talk about descriptivism is “whateverism”. If you come in saying there are no rules, there is data, what makes good writing, makes clear communication.
- any language rules you will not break?: mechanical rules. comes down to style guide. Break at your period of looking unprofessional.
- how have your and other teams responded?: if you’re being truly descriptive, they might not even notice. Reflect patterns that they’ve already established. Nothing in it stands out as foreign.
- data-driven is the only way to be descriptive. We have modern tools that us use big data.
Alex Garnett and Lauren Kiss – Doing Data-Driven Content Maintenance
- maintenance is hard
- cost time and money, doesn’t necessarily produce new content
- how do we do maintenance right?
- context: library: in-house content, external content, acquired content (acquisitions)
- KPIs: critical to measuring anything, keep in mind what are you intending to do with your content
- top-of-funnel initiatives: creating brand awareness and positive associations
- maintenance types: high traffic > opportunistic, relevant to new feature/marketing > tech-debt
- identify top-performing (Lookr) not updated in last 18+ months, or opportunities, linking to existing interrelated content
- add to maintenance queue (Jira)
- prioritize by expertise as needed, or requested by other teams
- publish
- tech-debt were based on tech writers’ judgment
- when doing something without metrics, have to be cautious of value
- qualitative insights:
- having small edit tasks fit into a work schedule make writers happy
- constantly creating long form new content is a big, focused commitment
- dedicating regular time to maintenance makes writing go more smoothly
- quantitatively proud of process
- have buy-in? in principle, but can change from team to team, year to year
- management can’t take this work for granted, need data showing value
- defaulting to skepticism makes sense, consumes ~25% of time
- method: KPI (traffic volume), categories (3: failure, neutral, success), median (instead of average)
- 3 months prior and after maintenance, ignoring month of maintenance
- if decrease, fail; neutral is 0-30% median gain in traffic; success = 30%+
- high-level data: able to say % of success, neutral, failed; outcome, KPI impact
- level deeper: split out outcomes by maintenance type: stacked bar charts, maintenance efforts, and incremental traffic
- tech debt maintenance success through power of SEO and interlinking efforts and success of legacy content
- detailed view: piece-by-piece basis
- takeaways:
- maintenance is not a loss leader
- always tie to metrics
- evaluate whether metrics are sufficient, or bette way to measure team’s efforts
- team’s KPIs generally not tied to converting subscribers
- demonstrate a commitment to content we’ve already published
- keep former writers engaged
- evaluators:
- iterative, reevaluate as needed
- doesn’t need to be informative, can be actionable
- aim to align between measure and KPIs
- partner with writers
- maintainers:
- maintain old content is far quicker than publishing new content and fun
- no one rule about when to archive, deindex, or update older pieces
- know and trust your whole library, create many more links
- try to have a great metrics colleague to show off your work
- style guide changed a lot since published first tutorials
- built reputation, but newer content is much more carefully edited
- sometimes changes are very small and quick
- being empowered to make and track them makes a big difference
Q&A
- prioritization of content. what surprised you in the data?: spiky traffic historically had bunch of weird shapes. Seeing trends impacting what was popular.
- one-person team, huge backlog: look at how much maintenance should be performed, and look at data to see impact. get piece-by-piece view
- after maintenance, marketing?: no, but if you are promoting it again, make sure to take that into metrics
- anchor to the median, set yourself up for success, take time to look at all data that you have, choose metrics that make sense, goals and stretch goals
- resources to tech writers to do more quantitative resources: was learning as we went, nothing at the moment.
- strategies for small teams?: find a way to show value for maintenance
Scott Truelove – Navigating the Future of Technical Writing in a Rapidly Evolving Tech Landscape
- a lot of information about AI and how documentarians can use it
- you don’t have to use AI
- we’ve seen changes in writing: typewriter, word processing
- constantly changing tech landscape
- timeline: early AI research focused on rule based systems and natural language processing (50/60s), early machine translation (70/80s), statistical approach and deep learning (90/00s), creation of RMT models (2010/20s)
- already use AI: auto-complete, auto-suggestion, translation tools, other machine learning; natural language processing
- benefits: increased productivity, improved content quality; virtual writer assistant
- drawbacks: fantastic liar, no new ideas (back in 2021 for learning), quality concerns/plagiarism, doesn’t cite work, makes mistakes, lazy, saves everything so can’t include any private or confidential information
- prompts: key to the engine: improve relevance which guide more specific or relevant needs or interests, reduced ambiguity and confusion, improved accuracy
- more is more with prompts, stack, iterate
- tips: be clear, specific, and relevant; use natural language; provide context, background, relevant details; ask open-ended questions; multiple prompts; experiment
- how can we use AI (non-exhaustive): transform text into instructions, persona based content, give more context, editing, taxonomy help, localization
- might be good for generating a first draft
- rewrite content for different audience
- can attempt to fact-check if asked, but can still get it wrong
- clear IA for app, taxonomy, give more info the more specific
- localization, but can’t trust what it says
- best practices: select the right tool for specific task, integrate into existing workflow, identify stages where could be most effective, evaluate/validate, maintain a human touch, avoid over-reliance, consider legal and ethical implications
- at the moment, best to just use as a first iteration
- never going to be replaced, writing needs human touch
- recommended tools: AIPRM for ChatGPT (plugin for Chrome to generate and save prompts), GPT for Sheets and Docs, ChatGPT Prompt GEnius (similar to AIPRM), Night Cafe (Image generation)
Q&A
– early adopter, saw a way to get away from drudging things, look at future of documentation and where it can go
– there’s nothing to stop company from getting rid of writers.
– it’s a language tool. Still need human touch, doesn’t have empathy. Still need people to edit it. Every tool has an application, it’s about finding the right place for it.
– security/legal: use common sense, imagine it’s being posted publicly
(Sorry, don’t have notes for a couple of the talks)
End of Day 2
Hope to see you next year!
