I was very fortunate to continue spreading the documentation gospel at Web Directions Summit 2022 in Sydney, Australia.
This talk has transformed as I’ve given it over the last several years. This edition highlighted the importance of creating accessible content.
In particular, accessible documentation should have:
Inclusive language. This starts with self-reflection in the ways in which we’ve internalized ableism, racism, sexism, etc in our everyday life. We cannot do better without recognizing where we fail.
Semantic HTML. This means your headers are not just visually larger than body text, but also represented by the correct HTML structure.
Meaningful alt and link text. If you’re already writing documentation and you take one best practice away from today, stop using “Click Here”. Replace it with copy that reflects the actual link.
This year I was invited to speak at Build Stuff in Lithuania and Ukraine. I hoped to convince developers that writing docs would make them better engineers, better colleagues, and better future-proofers.
Some of the talks I saw which deserve your attention:
In this conversation, we talked about what it’s like to work on Google’s tech writing team and my previous experience at Joyent. I spoke about the importance of multimedia documentation, creating proposals to tear down bad docs, and what it has been like to join the conference circuit.
Just a note, this conversation was one of my own and not on behalf of Google or Alphabet. My thoughts are not those of my employer’s.
I’ve got my next speaking assignment, and I’m going back to Eastern Europe! I’ll be speaking at Build Stuff Lithuania and Build Stuff Ukraine this coming November.
This talk was influenced by one I gave while I was an engineer at WNET.
Updated on November 13, 2019 to account for community and non-profit event policy.
I recently updated my website to include a speaking page, listing my previous experience and outlining my personal speaking policy. This policy is focused on conferences having and enforcing a code of conduct (boiler plate example) and treating all speakers equally regarding compensation.
That doesn’t mean all conferences must provide speaker fees, but it does mean that conferences should not pay or cover the costs of some speakers and not others.
Why does this matter? New / young / minority speakers are often taken advantage of. All speakers, no matter how much experience they have, deserve to be shown the same respect.
I was honored to be invited to speak at KnowledgeConf 2019 in Moscow in April (English marketing site and actual Russian conference site). I was the only English presenter among fantastic Russian talks, and I look forward to being able to watch them with translated captions!
My talk, “Creating compelling multimedia documentation,” covered the importance of considering the different methods of creating documentation, particularly video. While I did not specifically walk through how to make a video, I did cover when and when not to make video, considerations for script and storyboard creation, branding, and usability.
