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

Q&A

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

Q&A
– 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.

Q&A
– 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

Q&A

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

Q&A

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!