When users find a gap in your documentation – some jump from A to C that gets negative feedback – don’t just fix it. Ask yourself how it got there. Gaps happen because: Someone didn’t think users needed the topic. This demonstrates a misunderstanding of the audience. someone didn’t think about the topic at all. …
Author Archives: Irit Arkin
This isn’t the job you were hired to do
When you start a new job, you can’t really work without a mental image of the job: “This is my role. This is what I should be doing and how I should be doing it.” But that image is about 90% wrong (yes, I made that number up), and you need to let go of it …
Quick writing tip: What’s the default, and why?
As a technical writer, one of the most important questions you can ask yourself is “what are the default values of the choices a user can make, and why”. For example, if an option is disabled by default, what does that tell you about the average user and their workflow? Are you trying to protect …
Continue reading “Quick writing tip: What’s the default, and why?”
Recommended Reading: How to Think About Writing
Oliver Burkeman reviews the basics of thinking about writing.
I Wonder That You Will Still Be Writing; Nobody Reads You
Agile got (at least) one thing right: stop writing documents no one’s ever going to read. If you want to honestly assess what will or won’t be read – and therefore what should or shouldn’t be written – you should answer some basic questions.
Recommended Reading: Tools of the Trade
Tools of the trade, 2014. Everything from bug tracking to HR.
Don’t Let HR Block Your Next Technical Writer
First let me clarify – I’ve nothing against HR and their involvement in the hiring process. What I object to very specifically are two habits: letting HR choose who gets interviewed, and letting HR do the first interview and veto some of the candidates before they ever meet the technical writing team leader.
Testing Information Architectures
Usability testing for your information architecture – before you code.
Do not Hire This Person: Technical Writers Edition
Three things some technical writers say that should serve as a warning sign that you may not want to hire them: “I only need to understand it at the UI level”. If you don’t understand how and why things happen, you’re no better than the user. Anyone can read a field label to understand what …
Continue reading “Do not Hire This Person: Technical Writers Edition”
Do not Hire This Person: QA Edition
Written in collaboration with Efrat Wurzel Three things some testers say that should serve as a warning sign that you may not want to hire them: “I can’t understand a feature or start thinking about its tests until I use it”. Obviously there are some things that will click better when working with the feature. …
