As generative AI has become more widely available, we’ve seen how widely the quality of results can vary. In fact, there are several components that impact result quality, such as which large language model (LLM) you’re using, model size, and prompt quality.
As a technical writer, quality prompt writing is pretty close to a summary of a key job component: ask the right questions of the right people to get the best possible information to shape what I produce. I go to the subject matter expert (SME), who may be an engineer, a product manager, a UX researcher, or another technical writer.
In my day-to-day work for Google Chrome, some of my questions could be asked of an LLM, but that requires the model have pre-existing information or to be given the context within the prompt itself.
Prompt quality is impacted by the level of details provided, initial information accuracy, description of expected format, and so much more. Prompt engineering is the practice of asking better questions to generate the best possible response for your needs.
If you’re wondering how to be a better prompt engineer (or a better tech writer!), keep reading to learn best practices.
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.
I had the pleasure of editing Carie Fisher, the author of web.dev’s latest course, Learn Accessibility. Learn Accessibility gives web developers the essentials for building accessible websites and web apps.
To promote this new content, I interviewed folks who work to build an accessible web.
Melanie Sumner told me about her journey from spy to engineer, accessible design, Ember.js, and the importance of funding these efforts.
Olutimilehin Olushuyi told me about his move from the law to web development, building accessible community, and creating accessible layouts.
Elisa Bandy told me about her work for Google’s internal teams, developing accessibility best practices for the web. Her blog post has yet to be published, but look for it in mid-December.
It’s an honor to work on Google Chrome’s developer relations team. I have the opportunity to speak with experts and offer a platform with a huge audience.
We highlighted additional resources as a part of ChromiumDev’s Accessibility Week.
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.
I’m excited to announce I’ll be speaking at the Evolution of Technical Communication conference in Sofia, Bulgaria in June. Not only that, but I’ll also be leading a workshop!
How to assemble a quality writing portfolio
We’ve all spent a long time trying to decide how to craft the perfect cover letter and resume to apply to new positions. Often times we are also expected to present writing samples – if not in the application, at some point in the interview process. These writing samples are the key to showing potential employers that you can concisely explain a process in various mediums.
In October 2017, I decided to apply to Google. It wasn’t the first time I had applied—I applied in 2011 when trying to get a job post-graduation in communications. Back then, I never received a response to my application and expected similar results in 2017.
Although I applied for a product Developer Programs Engineer position in New York, I ended up getting an email from their technical writer recruiter the following week. A year and one day from the day I submitted my application, I signed an offer letter. And 6 weeks after that, I finally went to Noogler (that’s what they call new Googlers) orientation. It was a long road to get here.
