Write the Docs Day 2: Afternoon Talks

Notes from the afternoon talks.

Lightning Talks

Top 10 Myths: True or False?

A lot of things to learn. Top 10 myths:

  1. Nobody reads documentation.
  2. Docs like code.
  3. Just let the developer do it.
  4. You only need Microsoft Word. FALSE
  5. Docs maintain themselves. TRUE
  6. Technical writing is easy.
  7. You don’t need documentation because products are now intuitive!
  8. Docs or didn’t happen. FALSE — forgot need “it”
  9. DITA will solve all our content problems.
  10. We need a good technical writing conference.

Emotions and Unicorns

All communications has an emotional output; causes emotions. Emotions are messy. Shepherding emotions is part of our job as writers. We should think about this. If you know what emtional response you want to facilitate, you can use that to guide the success of the docs.

Technical Writer Ops (TW Ops) + Community = <3

under resourced technical writing group. Empower you to build better tools for yourself. Setup, staging, publishing flows are hard. Installing stuff locally is time consuming, getting everyone to see what proposed docs would like live is hard to set up, so use portable shareable containers.

Use Docker to install and run container. So contributor can be up an running in minutes.

Teachers as Documentarians

Days are dominated by technology, but technology is not why we succeed. We are successful because we teach.

Sometimes it's a barrier to users, obscure our goal.

Tech Docs Management

  1. Know Your People: strengths, weaknesses, motivations
  2. Be an Advocate: can be isolating, show value of your people
  3. Support individuals' networks: don't get in the way.
  4. Be the backstop: so not overwhelmed with requests and work.
  5. Give Feedback all the time: don't get it much from the larger organization.

Picking Your Battles: How smarter battles lead to better results


Internal battles: fighting with yourself. Some of our biggest battles are with ourselves. Solution: Sort it out: what I have to do, what I want to do, what I can do.


  • Win as a team: usually do things as a team, battle to find best solution not to win a fight, battle which results in team discord is usually not a winning battle.
  • Battle better: focus on issues, no personalities. Gather and use data. Pick the right time to battle. Go global for distributed teams (all individuals call in, rather than individuals vs. big group in room).
  • Letting go isn't quitting: trust your team and the process, validate the idea and learn what works note what doesn't, take what you learn during validation and iterate.

Jesse Seldess – Bootstrapping Docs at a Startup

Technical Writer at Cockroach Labs. 1st tech writer when started. 0 user facing documentation. beta release <6 months.

Knew had goal, but didn't know where to go or where the goal was. Didn't want to spend a lot of time going down paths that would end up in dead ends.

Bootstrap the docs: write the docs your users need quickly, while establishing a flexible framework for growth using available resources.

What to do: learn, prep, build. Feed lots of birds with a few seeds: write FAQ, choose the right tools,

Write FAQ

  • give users clear sense of product
  • what are the questions? focus on differentiation, consider users' frames of reference
  • interview founders and lead developers: not at the same time, but ask same questions:
    • Why built product?
    • What problems does it solve and for whom? Scaling, survival, consistent, SQL
    • How does it compare to what's already out there?
  • what you get: jumpstart on learning, discovery of essential/unfamiliar topics, valuable piece of content

Existing Resources

  • reading (press, blog posts, design docs, specs, wikipedia),
  • watching (tech talks, meetups),
  • interviewing (founders, lead developers, other colleagues, early adopters)

Prep: Choose the Right Tools

  • need to be: quick, flexible, available resources
  • quick: write (not too much about presentation), iterate (updates without losing history), review (easy to share, give feedback), collaborate
  • flexible design: easily customize structure, have control of layout and styling
  • available: fluent with suitable tolls? can learn quickly? can afford?
  • chose: GitHub, jekyll, TeamCity (automated testing and publishing)

Build: Write a quickstart

Write the docs your users need quickly:

  • doing (vs. understanding); must do, should do
  • ask peers to demo getting started (not at the same time), but ask them to show you the same things
  • find unspoken prerequisites or assumptions, pull peers in to help with blockers, find clearest/simplest way
  • demo to stakeholders to make sure got it right, and figure out what users should do next

Carl Parker – Intelligent Documents and the Verifiability Crisis in Science, Tech Writing, and Life

Experiment: set out to replicate the findings from a hundred peer-reviewed published research papers in psychology (2008). 61 of 100 could not replicate original findings. Further studies showed similar results: 70% failed to reproduce at least one other scientist’s experiments, 50% failed to replicate own findings. = replication crisis.

Reproducible research: the ability to re-enact the experiment was too high a bar. Proposed reproducible research instead. Any published research make available both data that was collected and the code that processed the data. Could validate data themselves.

Problems around process and tooling. Needed to find a way to keep research paper and code together and in sync.

  • Most data processing in R. Developed a couple of solutions:
    • RMarkdown: extensions to enable Markdown to embed executable code.
    • Knitr: tool that builds the Rmarkdown to various output formats.
  • Process: article.Rmd (with code in R) -> Knitr -> article.md (with output from code) -> Pandoc -> multiple formats
  • GitHub: publicly accessible repo where data and files can be uploaded

Documentation and Sample Code

  • verify that code snippets in the docs work
  • keep the code snippets in the docs sync’ed with actual code
  • need to scope the size of snippets so that concise but also works
  • provide the customer with enough information to reproduce the result
  • solution: bring the technical writing and the sample code into a single document. User only sees snippet, but whole sample code is executed in the document.
  • Knitr supports other languages including C(++), Python, Ruby, Bash.
  • Knitpy: more robust support for Python code.
  • Jupyter Notebooks: mix text, code, and can interact with code.
  • CWEB: one of the first technologies for this purpose.

Social Discourse: Environment of misinformation

lies, fake news, and statistics. Fake vs. vertifiable news. Idea is to read or hear news and then go to repository of code, sources, references to create article. Verifiable news could:

  • call web services
  • access online databases
  • scrape a website

Example: How close was the election really? What if 1% of electoral votes went the other way? Can get electoral votes from Wikipedia and popular vote from Cook Report’s Google spreadsheet, convert to R data structure and merge, write code to summarize, map, and calculate.

Take Away

Example of explore question grounded in data, and construct document that can be verified, inspected by others.

These technologies are available now, and will become more ubiquitous. These intelligent documents will eventually displace documents that promote fake news.

Lightning Talks

Sorry if the notes are limited. I had a lightning talk in here.

LiquiDoc for Complex Content


Told have to single source all content. Real complexity: single source of truth, internally and externally. Output to anything/formats, kept in source control, have to sort as well. Built LiquiDoc: simple Ruby script that precompiles data into content source for further compiling into docs or interfaces. Can output HTML, inline tooltip, JSON from YAML.

Documentarians are the best audiences!

  • Tech support tickets are an historical resource for knowledge articles = KCS model
  • Kepner-Tregoe Resolve or at least The New Rational Manager
  • we all deal with weird issues
  • we all gained far more than we expected: so thank you

Taking Linearity Out of Technical Training

Mary Ellen Niedzielski

  • feedback that training content was the weakest part
  • courses made up of “modules” but were not modular
  • mistakes haunted learners through subsequent courses
  • problems addressed: linear flow didn’t reflect non-linear flow of work of software
  • removing linearity
  • introduced learning plans, students start learning experience from any module by loading partially build app, no prerequisites, provide solutions so don’t give up from frustration
  • managed all github actions for students

Write the Accessible Docs

Full post

5 Lessons from 5 Years

Not all documentarians are tech writers.

  1. Let go of the words. Everyone is in a hurry, so must be concise. Recommended book :Letting GO of the Words by Redish
  2. Writing about code =! writing code. Not true that need to learn to write code to be able to write about code.
  3. No one reads my super important call out if it looks like ads. Use bullet points = valuable, concise info lives here.
  4. When awful at delegating, examine why.
  5. Respect my SMEs’ time but respect mine too.

Extra: have personal motto.

What’s Up with the Floor

This is a sprung or floating dance floor: comprising of 3 layers of wood slats, then 2 more layers to make the continuous floor. Patented in 1905, built in 1914, only one on West Coast? Exist to help people avoid physical issues.

The End

Thanks to everyone who helped make Write the Docs Portland 2017 awesome!
bunnies in a pile;

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: