Lately I’ve heard a lot of buzz about a myth: writers can’t program and programmers can’t write.
Most of the buzzing is from frustrated and philosophical writers who argue that the myth is patent bullshit.
I agree, but I also find myself asking: Why does the myth exist? Why are we talking about it now? Why does it matter?
The myth is a product of our professional identity and the prevailing development culture. A set of defense mechanisms designed to shore up and augment our sense of professional self-worth.
In the beginning (or at least somewhere close to the beginning) there was the question: are you a writer or an engineer, non-technical or technical?
As you prepared for your career, you put faith in a simple answer: your education and training reinforced a professional classification tailored to fit into an org chart where you could clearly see what lay upstream and downstream of you in the Gantt-chart waterfall of dates, deliverables, and dependencies.
After you’ve worked to stake out your place in the greater scheme, it’s natural to feel territorial. Anyone not of your classification doing your work is an aberration and a threat. Threatened people defend themselves by cultivating myths aggrandizing their own classification and trivializing others.
Threatened engineers reassured themselves that coding is an exacting discipline that requires years of indoctrination, inherent talent for mathematical thought, and the manipulation of arcane technologies that outstrip mortal human understanding. Writers were interlopers and pedants whose technical ability topped out at spellcheck in Microsoft Word and who wasted time asking stupid questions and arguing over the utility of the semicolon.
Threatened writers consoled themselves in the knowledge that writing is an exacting discipline that requires years of grueling practice, inherent eloquence, and vast reserves of empathy for identifying with and catering to the target audience. Engineers were nerds who could only communicate in geek references and body odors, and should be kept in their dark cubicles far away from the customer and anything customer-related.
Another defense mechanism that reinforces the myth is self-serving specialization: My job is secure because the work is too intricate or important to be left to amateurs.
You see this reaction in many professions. Need to swap out a light switch for a dimmer? Electricity is mysterious and dangerous. You should call an electrician. Need to change the oil in your car? Cars are messy and complicated. You should take your car to a mechanic.
The message is “You should leave the job to the professionals.” In our case, the myth is strengthened into an admonition: programmers should not write and writers should not program.
Why are we still talking about this? Why the groundswell against this institutional divide between technical and non-technical, leading to the rise of code camps for non-programmers, and write camps for non-authors?
Granted, I wouldn’t want an amateur to upgrade the electrical service to my house or rebuild my car’s transmission.
Likewise, I wouldn’t expect the typical writer to design, build, and deploy a fault-tolerant, low-latency messaging server; or the typical engineer to develop a single-source doc project for print, help, and product tours with adaptive overlays.
Nonetheless, significant contributions can be made by amateurs with a basic understanding of the technology involved, some diligence, and curiosity. Older development models don’t leave much room for amateurs.
In theory, development models like the waterfall and its derivatives promise efficiency. After all, efficiency derives from specialization. Focus on the one thing you do and you will be the best at it. By logical extension, if you arrange all those specialists in a cascade from one dependency to the next, then at the end of the cycle *POP* you get your best product.
In practice and in my experience, it didn’t feel efficient. A grueling development deathmarch of changing requirements and blown dates too often led to an end result that few were happy with, least of all the user.
The only time set aside for feedback was at the end. We called it a post mortem, which really set the tone. All groups sat in one big room. It was the only time we all got together apart from holiday parties and company picnics. With the discussion guided by the head of engineering, we sifted through the stew of resentments at the end of the waterfall, trying to identify failure in a constructive way and trying to find success to celebrate. We’d all then vow to apply lessons from the past cycle to the upcoming cycle and try to do a better job next time.
It felt like we were stumbling in the dark and this puzzled me. I worked with a bunch of generous, interesting, and scary-smart people. The freewheeling startup culture, the mix of personalities, and my own attitudes had me disregarding lines of authority on our org chart. For example, before Javadoc had a way to flag internal content, I started developing my own doclet to implement an @internal tag and, when I got in over my head, consulted with a friendly senior engineer. He listened to me and gave me some critical guidance.
I wasn’t enlightened, merely naïve. I grew up the son of a bench technician. Both my mom and my dad filled our house with Heathkit electronics. The way I was raised, technology wasn’t esoteric and impenetrable, it was the cool stuff that you used to get things done. We held a deep respect for technical education and certification, but we valued making and doing.
But even in the startup, the technical/non-technical myth would rear its head. For example, an executive’s reaction to my queries about a new product was just redolent with assumptions: “Oh, it’s much too early. We don’t want to waste your time. There’s nothing for you to take screenshots of yet.” Even one of my favorite senior engineers was caught out in an unguarded moment: “So, Phil, there’s this build tool called ‘ant’.” I had to cut him short: “Dude, the Doc Team has been running its own daily builds for over a year.”
We’re talking about the erosion of this myth because diligent and curious professionals have grown dissatisfied and disillusioned with older development models and their proscribed roles. They are taking to social media to express their frustration and banding together to effect change. These folks are driving an evolution in development culture from step-wise, linear, and parochial to continuous, iterative, and collaborative. In the folk language of the day, we’re being disruptive.
It’s not just writers chipping away at the myth. Engineers are just as frustrated and they are discovering that communication can be an effective salve for and inoculation against frustration. For example, the developer and consultant Tomas Björkholm, while framing his principles of lean documentation for agile methodologies, pretty much lays out the fundamentals of technical writing:
- Identify your audience and their needs
- Structure your content for easy access
- Keep the doc focused
- Use images
- Keep it updated and relevant
So why does all of this matter?
It matters because an ever growing number of professionals from all disciplines recognize how the myth shores up the institutional barriers between groups in an organization and the concordant divide between “product” and “documentation”.
Movements like DevOps and #writethedocs, built on respecting your colleagues’ abilities and on the shared desire to do good work, make good products, and keep users happy, stretch the traditional definition of “user advocate”.
How does working contrary to the myth make you a better users’ advocate? Again, from my experience (please forgive the software jargon):
- I’ve built simple UIs in various technologies for my own tools and for screenshot mockups. I know enough to get myself into trouble and to relate with a crew of supremely talented app developers. I suggest component-based help for our new adaptive UI. A developer approaches me with several jQuery plugins and asks me about the feasibility of developing product tours. Working closely, we all get excited about how we can elevate a clean UI to levels of UX engagement and delight for our users.
- Documenting a new REST API, instead of speculating about how users are going to use it or inferring use cases from the methods and resource names, I ask our Technical Account Managers for help. Their direct experience with customers yields API doc that benefits all of our users with real-world scenarios and examples.
- Our Support team approached me with a proposal to refactor 50 pages of PDF on a user “hot spot”, a part of our system that is very important and very complicated. The end result was a tightly focused 13 pages of guided tour written using vocabulary that customers actually use, grounded in years of Support tickets and experience.
By dispelling the myth we have a better chance at destroying an even more pernicious myth: documentation is, by its nature, stale, irrelevant, user-hostile, and a waste of resources.
It matters because breaking down the myth gives us all a better chance at delivering the products that users actually want and keeping those users happy.
It matters because in the end we are all, technical and non-technical, users’ advocates.
Worth Reading
Here’s a sample of thoughts from folks who inspired this column and who continue to inspire me:
Neal Kaplan:
Writer as QA: https://twitter.com/NealKaplan/status/770665360185884672
Killing the myth: https://customersandcontent.com/2016/07/25/we-need-to-kill-some-dangerous-myths-programmers-cant-write-writers-cant-code/
Sarah Mei (@sarahmei):
The evolution of technical and non-technical: https://twitter.com/sarahmei/status/763158652509233152
Andre Goulet (@andregoulet):
The requirement for and advantage of technical/non-technical duality: https://twitter.com/andreagoulet/status/771306615521685505
Things in Squares:
The categories we’re sorted into and the difficulty breaking the sort: http://www.thingsinsquares.com/comics/make-a-choice/
Golden Unicorn (@Bradamante):
It’s cute to watch coders discover the challenges of writing: https://twitter.com/Bradamante/status/762025857883906048
