Write the Docs 2023: Day 1 Notes

My notes from the presentations on the first day of Write the Docs Portland 2023.

Ryan Young – Is it (layer) cake: Thinking in content levels

  • Users: what do they want? who are they? let’s find out
  • it’s good for anyone who is building products to think about their users
  • Stripe has a user first mentality
  • turns out, they’re pretty normal people, just trying to figure out how to do something
  • In the case of Stripe, there’s a lot of stuff users need to do outside of Stripe
  • usually they’re looking to just accept payments, but also subscriptions, send invoices, or something something
  • try to anticipate this with the IA and make sure people are guided to the right places
  • people have jobs to be done, and come to the docs to do those jobs. If they don’t know
  • have a pretty good feedback system
  • started reviewing some of the feedback
  • a lot of users were frustrated, which was dispiriting to see, try to make good docs, easy to use, full of useful details
  • we thought we were giving users what they wanted, so why getting so frustrated?
  • some themes:
    • too many options: want to understand all the options
    • inconsistent in the way we told users to get started, users felt choices were contradictory or mutually exclusive
    • too much information can’t utilize: might not understand context, or how to apply to their problem
    • wrong scope: too broad/specific
    • too technical: initially targeted at developers, seeing different users who didn’t want to invest time in writing code
    • not the right information:
    • not clear where to start, where to go next: when done with initially started guide, wasn’t clear where to go next
  • Remember malls? Memories of spraying perfume/make-up which was disorienting experience. Similar user experience. Really liked store directory, because it had a map and list of stores. Thought this is what’s missing, map or at wrong resolution.
  • Seemed either had high-level overview or low-level docs.

Docs are maps for users before they’re instructions

  • strive to create products that ideally are intuitive and don’t require instructions
  • usually read docs because they’re a little lost
  • looking at all aspects of the docs to guide them
  • Stripe home page has a lot of content, but meant to get them started quickly. Other links also guides on how to do something.
  • “escape hatches” to skip straight to references like the API
  • lots of high level overview pages
  • high level: index pages, landing pages, overviews: how to take the first step, high level maps
  • low-level: focus on execution and accuracy, when they’re here, users know where they’re going and have a decent understanding of products and services
  • have immersive quick start, copy/paste code samples, reference
  • low-level: integration guides, quickstarts, references
  • what we seem to be missing is a mid-level
  • if high-level is orient users, low-level help users implement, maybe mid-level helps users make decisions
  • mid-level: bridge, something that’s orienting, lower layer than overview, a little more depth and usable information, not just presenting options, but help understand how to reason about those options
  • design pattern same as high-level, have low-level docs, then created middle-level, only know a couple of things like don’t write code but want something payments-related
  • like pieces of typical integration, and context, use cases/examples/jobs, like integration pieces for each use case
  • users liked it, did what they wanted
  • weren’t seeing the same comments
  • when complaint about lack of common use case, could copy the pattern and add use case
  • also used for complex, error-prose use cases
  • we’ve used it to containerize concepts
  • compatibility matrix by product
  • middle layer: help explain use cases, broad concepts
  • Idea from wayfinding
  • High-level = orientation, middle = decision, low = implementation
  • you can imagine users going between and in/out of the different layouts
  • what’s next? keep building framework, talking to users, evaluating success, updated docs based on user feedback


  • every page has thumbs up/down with prompt, some multiple choice based on up/down, and free text box
  • user interviews are best way to understand, though most time intensive
  • orientation level where most users start, but seeing feedback where they want to prefer to go straight the decision level
  • metrics: constantly collecting and reviewing. subjective feedback, page views
  • negative feedback: definitely try to make sure it’s not a docs problem first, retrace users’ steps. Sometimes combination docs/product.
  • Duplicated content: don’t think there’s a lot of duplication. might reuse some low-level. More about what user’s trying to do, rather than how author’s trying organize.

Adam Altman – From resistance to adoption: navigating the challenges of docs-like-code

  • information overload is confusing
  • if you’ve thought you can’t succeed with docs as code, put those fears away
  • many think that you need a computer science degree or support from a giant company to make docs as code succeed
  • here to tell you that’s not true
  • for those beginner: path to adopt docs as code
  • for experience people: learn how to help those who look to you for advice
  • ABC’s of Docs strategy
  • context: redoing marketing site, but docs site was in a separate CMS tied to support system
  • why do developers always make the best tool for themselves? will we be stuck using bad CMS’es forever?
  • review, collaboration, audit trails, for non-developers. Unified marketing side, blog, workflows
  • adopt open standards
  • convert files into a website. Used Static Side Generator (SSG)
  • brought together teams to work together
  • docs-as-code was a transformation
  • unified website, unified team
  • A: Assess: is it right for you?
  • B: Build: try in under 30 minutes
  • C: Convince: how to ethically convince boss/company to adopt
  • Build: 1-2 pages for each content type, scope/size of migration, test with an outsider for one content type and get testimonial, verify estimates, freeze/migrate
  • the new part was preview page
  • test with non-developers
  • 5 different systems was a bigger pain than asking for help to resolve git conflicts
  • skip the migrate until convince team if have a lot of content
  • Assess: is right for your company? Industry, role composition, content types
  • doing the work in advance makes it easier convince if can demo and estimate
  • are there any software developers anywhere?
  • user generated content, complex data structures don’t want stored in source control
  • Convince: explain, find transformation, appraise value (cost-benefit analysis), pre-handle objections, presentation
  • if you can’t convince yourself, stop
  • if it won’t positively impact the company and lead towards vision/goal, then stop
  • explain it as if they’re a 5 year old. simplify explanation
  • Example: like “shared drive” but better because you can see who changed each line
  • Find transformation: disconnected vs. connected, full service vs. self-service, 1 x 1 vs. n x n
  • can understand cost from size and scope of tep before in build phase
  • time, effort, products, hosting
  • benefits: transformative outcome, chances of success (more tried, tested, more likely)
  • demo migrated content, shows likelihood of success
  • come up with short story of each objection: I used to think __ (false belief/objection) but then __ (discovery) I tried it, and ___ (result)
  • many don’t know what their false beliefs are, or not able to verbalize
  • other examples: resistance to change, difficulty integration into other tools, handling complex formatting requirements, lack of support of realtime collaboration and feedback, concerns about git/markdown.
  • put all of this into presentation
  • how: best as interactive

– convincing: find the one person who will be the shining star, and build a case for how it’s better than google docs
– money can be a reason, but should really find a better, positive reason
– no developers on the docs team: always good to find some reason, and part of big community. Can get help from community. Often times, developers can unblock you. They just need 15 minutes.
– some CMS’es use docs-as-code for their documentation. You can have public repository, and people can contribute. You can try docs-as-code through open source repositories.

Linda Ikechukwu – Myths, Mistakes, and Missed Opportunities: Lessons learned from a year of interviewing technical writers.

  • showcase technical content creation roles as viable career paths for people getting into tech
  • draw valuable career insights from people who have towed the path that others with to
  • to assuage doubts, need to share the story of successful tech writers and started the idea for an interview series
  • application: submit a style guide formatted document, use exact verbs from job posting in resume, use metrics, writing certification might help, different docs types in portfolio
  • no writing samples? contribute to one or more open source projects
  • levelling up: talk to engineers about major challenges, learn one fundamental programming language, just enough to understand how things are built, pick a popular language or one used within the company, solid and basic understanding of how things work to bridge the technical gap between you and the engineer
  • freelance to find more clients: makes friends with people and do free things for them, write a free article/tutorial/guide based on their product, share and amplify their stuff on social media, offer to review and polish stuff for them
  • tailor bio to niche, start with lower-priced gigs, keep first 2 lines of proposals catchy, include keywords
  • transition from tech writer: talk to your manager (easiest to transition within company), start doing the job,
  • might get new role
  • content writer, developer advocacy,
  • transition to manager: same as before, talk to your manager, start doing the job, very different from individual contributor, doing less writing
  • if great documentation was easy to write, it would be more common
  • be willing to learn, test yourself, and go beyond what you know. Evolve.

– so many paths into tech writing
– might not always be easy to talk to your manager (may depend on the individual)

Lightning talks

Ryan Mackling – People are not logical

  • boil down to stimuli in, trigger chemical reactions
  • highly emotional and logic are both from the brain, so it’s not as clear cut as we often think about

Ashley Gordon – Tech Writing Internship

  • Luma Health as senior tech writer
  • had an intern for the first time in 2021
  • didn’t have a lot of support
  • great for students
  • for business: new point of view, additional project support
  • have a plan: what they’re going to do, how they’re going to work with the team, intern’s presence impact team, improve, time
  • more cost effective
  • Example: 3 months: first month onboarding, 2 months: 53 articles edited/created
  • gather metrics for project/internship

Matthew Shaver – Lego your docs

  • how you can use lego documentation to keep your documentation light, easy, whimsical, fun
  • build a journey, keep the destination in sight
  • hands-on approach
  • connect the pieces, sprinkle small wins along the way
  • make knowledge sharing the centrepiece of the process. Example: Adobe photoshop top video not from Adobe
  • whatever pieces are left, clean up

Daniel Murphey – Release-ready Docs: How a 2-person team keeps a help center consistently accurate

Release readiness is the practice of preparing the entire team and your customers for changes.

  • challenge of help centre keeping up to date
  • managed to keep it up to date with day 1 release day
  • do the advance work needed to make all help centre articles and their translations accurate and completed within 24 hours of a release
  • continue to adapt and change
  • why we do it: sanity (no backlog), simplicity (20-50 edits), customer trust (don’t think other articles are out of date), team support (team can point to docs, for team to keep up to date), AI (chat bot can present out-of-date information otherwise), etc.
  • others in the company with positive feedback
  • Foundations: documented processes (style guide, meetings, touchpoints, standards), planning and organization, relationships and communication
  • don’t talk to customers a lot, so rely on others
  • have members of broader team do peer review
  • Process step 1: Awareness: 2 months of visibility into changes coming up
    • communication with product teams is key (external roadmap, slack channels, meetings/touchpoints, UX review)
    • continual refinement
  • Process step 2: Scoping
    • initial gut check
    • normal release (20-50 articles) = 30 days before release ; simple ‘todo’, use custom task fields
    • big release (50+ articles) = ASAP ; long-term scope: “buckets” for pre-work
    • new articles, existing, chat type (text/image), change issue (which changes affect each article), work timeline (future proofing)
    • use Asana for task list, changes in Intercom
  • Process step 3: Drafting
    • pre-work (text changes)
    • combo opportunities (audits, typeforms, later release future-proofing)
    • take screenshots in the staging environment; pay attention to if it matches the spec
  • Future proofing
    • Simple screenshots; very image rich, only what’s necessary for context/comprehension
    • future proof dates: show future dates
    • adjust wording for later changes; example: toggle to “Yes” vs. toggle activate
    • safe exclusion: when not focus, removing it from screenshot ahead of release; use with caution!
  • Asana: articles move through status-based sections, automation rules for peer review, localization, notification
  • move quickly, but sensibly
  • Process step 4: Release
    • wait for announcement
    • publish edits, what’s new page
    • localize changes
    • celebrate
  • something unexpected will happen: might not get everything done, adjusted process
  • tips: start right away: take stock, make a plan, build process, identify tools, start forging relationships, work on communication, pursue efficiency, and iterate
  • relationships and communications: companies need us to do our best, have basic needs, be bold (but not boisterous or demanding), ask questions, find who does what, ask inclusion in kickoff meetings, ask for monthly touchpoints with PM/PO, ask for access to design and release boards, communicate documentation impact
  • give back: report bugs, offer feedback, suggest UX copy
  • have a say in product, leads to better docs
  • pay it forward: share what you learn, meetings, channels (sales, support, marketing)
  • more willing to share if impact more teams
  • development don’t normally talk to customers, more helpful products
  • shout out your supporters
  • get hundreds of feedback requests


  • 6 month audit cycle: normally trying to move quickly and impmlement changes necessary for the release. Audit is to catch changes needed to update to current style guide, and review article as a whole.
  • Automation: writer (like grammarly), can plug in terms of style guide; highlight ‘no’ lists to ‘yes’ list; snippets feature
  • multiple technical content teams: understand that some content like videos aren’t release ready, reuse content

Docs for Developers (Unconference session)

  • how do you get knowledge hoarders to share? play “what’s wrong”
  • How did you find the book? better thanks to expert editorial guidance
  • easy to propose a book, but many publishers scared of book written by 5 people: creative differences
  • had a plan
  • shared authoring tools: google doc, chapter basis, peer reviews of each other’s chapters, change tracking function and leaving comments
  • had a style for unclear or points likely to argue about, for consistency
  • nice thing about working with other writers, knew what they were doing
  • one person edited all of the chapters at once
  • publisher editor comments were unexpected, had to push back on some
  • had the freedom to design cover, and artwork
  • when translated, realized could have written better
  • wouldn’t write with 5 authors again, so many moving parts
  • worked because of the times
  • 2 or 3 authors is likely ideal
  • how have we changed how we talk about developers from start of book to now? refined understanding of the problem. originally effective software documentation, or minimal viable documentation. When thinking about developers as teams that we work with, but more about unsupportive developers in small teams with no writers. Talked to many developers about book, the range of perspectives of developers was a strength
  • many developers even in large organizations, because docs were part of their deliverables, found it useful
  • range of involvement of developer/writer: best is hybrid situation. Who built it just write something down, and then documentarian polish it
  • recommend tech writer team in engineering to align messaging, others think support
  • some engineers are hyper focused on writing everything down, very long, very technical
  • when engineers write but don’t follow style guide, how strict should you do? as strictly as style guide calls for, cut down 20% as needed, to be consistent, explain why; work with engineer to get to a good point; technical writing is part of onboarding
  • style guide exists for a reason, better experience for users, frame feedback that way, rather than needing to “follow rules”
  • point out what was written well
  • have another book and a half of material written, but book was better in the end with material cut
  • originally said 8 months, then 1 year, then 15 months, took 18 months; were gentle with ourselves, enough to keep motivated, but also to live in the environment
  • proposal took 3-4 months
  • divided chapters that were passionate about, one wrote a “test” chapter
  • the story helped to solidify the chapters and narrative
  • book repo vs. other format, like online open-source resource: wanted something to hold, persistent, finished, medium pushes you to be different, can’t hyperlink out of a physical book, difference in boundaries of maintenance, book is constrained and could be done, clearer model for paying people for books, opportunity where there was a gap

Dan Grabski – Zen And The Art Of Automanually Creating API Documentation – An Inquiry Into Process

  • goal: share how to write better API documentation, want it to be: consistent, clear, easier to maintain
  • what are we trying to fix?
  • client-facing API docs isn’t up to date, or doc updates lag behind API changes
  • doc created by multiple microservices look inconsistent
  • doc created by developers isn’t “client-friendly”
  • support for doc outside of tech writing team isn’t always the best
  • create, generated, display
  • how to make things better? incremental approach, working with humans
  • incremental: just because not 100%, isn’t worthless. Can’t change the world on our own, but doesn’t mean our work isn’t important. “Don’t let great be the enemy of the good.”, hedge against unknown changes in scope/complexity, less chance of large-scale failure
  • not completely auto or manual
  • use manual process to learn how things work, chance to debug the process
  • start doing improvements iteratively
  • standardized copy in a central location
  • automatic OpenAPI Spec file generation
  • automatic posting of files
  • Changes in scope/complexity: can uncover changes in scope/complexity earlier, reduces wasted work
  • manual before automatic: programming
  • more flexible handling differences in input and requirements
  • build a more robust, ongoing process
  • interpersonal improvement: consolidates efforts across multiple teams, reduces wasted work due to misunderstandings, reduces conflicts
  • more tools in toolbox
  • position vs. interest: get at the root of what’s actually needed
  • 5 whys based on root cause failure analysis by Toyoda: ask why 5 times
  • talking past each other: are you making different assumptions? have different priorities?
  • how to get buy in? identify the end goal, make a connection between effort and the goal
  • sometimes nobody gets what they want
  • trick is getting people to believe they’re being listened to
  • can better anticipate problems
  • failures are smaller scale
  • nothing goes completely to plan


  • how would you solve API versioning issue? ideal only most up to date. OpenAPI specs can flag things. Clear notes in descriptions.
  • who owns the API specs vs. docs? so dependent of the culture of what’s set up. Who do we want it to be owned by?
  • manual to auto: might get the whole process done for one service, or all services, linting on content
  • balance gate-checking with what you get from devs? if completely automatically, things can get dropped. Another reason to start with manual.
  • how to get start and know which tools to use? can go into code and create OpenAPI spec file automatically? start there that can lead to a better process
  • grouped Rest API docs by use case or linear? Seen it done well both ways. A little bit more by use case.

End of Day 1

See you tomorrow!

Chipmunk in flower fields

Author: Cynthia

Technologist, Librarian, Metadata and Technical Services expert, Educator, Mentor, Web Developer, UXer, Accessibility Advocate, Documentarian

Leave a Comment

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: