Tech Mentor: Or, How to Help Your Young Writer Grow Up

Photo by Star of the Sea on Unsplash

The difference between good writing and bad writing is more than simply reader enjoyment or understanding. It is career advancement or publication rejection.

Seem overstated? It’s not.

In the technical circles I move in, I watch decent writers get held back every day, every month, every year from being promoted or advanced all because they are just that: decent. They are not great or exceptional, visionary or learned. They didn’t have anyone come along and nurture them from decent to excellent.

And that’s a darn shame, because a decent writer has a fair-to-middling chance of becoming really, really good if they have the right teachers along the way.

My mother was an English teacher, and her mother before her. But they are not the people with whom I credit my exemplary grammar, although they contributed a fair amount of dinner table chat about language and style. I can say with no fear of correction that I became a much better writer than my mother. In truth, my sixth grade grammar teacher, Marcia Saiers, taught me all about comma placement. Her husband Tom taught me in ninth, eleventh, and twelfth grade and from him I learned nearly everything else about composition and style. He was an exacting instructor.

But then I went to college, and whoo daisy my options expanded.

Then I got to work, and my technical mentors hit me like a squid to the face.

Writing communicates. It holds power that no other means of transferring information has. I’ve published too many essays and articles to count. Some are technical, others personal, but each one conveys information that I believe to my very core is essential to the reader.

Bold statement, I know,

How did those writings become…”essential?”

Those two teachers I mentioned, the Mrs. and Mr. Saiers – their approach to teaching me writing was steeped in what I refer to as “classical redlining.” That is to say, they took red pen to white paper and made it appear as though they had opened a vein. I submitted much writing to them and they marked it up, showing me error after error, and I corrected those errors until my writing met their exacting standards. They adhered to the Strunk and White school of thought, and I learned by making those copyedits time after time after time. No contractions, limited use of first and second person. Rare, if ever, beginning a sentence with a preposition, ever and always “omit needless words.”

These two mentors consistently made local copyedits, those that were specific to my work, bringing my narrative into hyperfocus, showing me how to defend and support my writing.

This is what I do for younger writers now. This is how I help younger writers learn to synthesize their verbose thoughts into the crystallized necessity and economy of words that readers are hungry for and little more.

My mentors gave me structural edits. They taught me effective logical argument. In fact, when I took a philosophy course in undergrad, I was prepared more than ever to grasp fallacy and linear argument. New writers will make two recognizable errors: first, they will write start to finish, and second, they will include details of their journey. I learned to become the technical writer who understands that no one cares about the labor; everyone just wants to see the baby.

In mentoring a new writer, I cannot overstate the importance of side-by-side writing, even though most will balk at the idea. Writing closely together, handing off writing as a collaborative act is a process of genius for technical writers. A bottom-up writing approach like this saves countless sessions of redlining merely by watching the thought process unfold. A younger writer gets to see a more seasoned writer’s approach, and vice-versa.

When I have mentored younger writers, I love to see how they approach a process and by seeing them write, I can note various flaws in their structure and rather than making corrections at the end, we can decide together how to implement a better flow or argument. We work through revisions in real time. I do some writing directly in front of the mentee, and they can see how I think, what choices I make, and often I articulate why as I go.

Side by side co-writing takes time. It’s not fast, and it isn’t pretty. But I have found that when I do this, I end up with a better writer mentee in a few weeks rather than a few months, which is a pretty grate rate.

Learning effective technical writing is difficult and takes practice, as does any skill. There are layers and nuances, perhaps more than many professions. There are ingredients and customizations just as there are to a good, freshly baked pie.

When you are ready to dig in, though, the elements that blend together well are distinct and sharp and well-defined. And it all tastes pretty good.

Four Ways Gen AI Will Help Tech Writers in 2024

Image courtesy of Nick Morrison on Unsplash

We’re a few weeks into 2024 and now that we’re past the “best of” lists and the “year in review” lists, there’s a bit of time to take a look at what we might find most productive in the coming quarters. I always enjoy taking a few deep breaths once the frenzy of the year-start fades to look at what I might find truly useful as the daffodils peek their heads up in the park and I begin to feel the true momentum of the year take shape. I kick off the winter blues and roll my sleeves up to dig in.

This year, my company is more sure than ever that we will harness the ever-growing powers of AI as it enters a more mature phase, and I for one am grateful for the embracing of that stance. Artificial Intelligence, especially generative AI, is no longer just a buzzword. Companies are beginning to sift through the hype to discover what is really providing value and what was just marketing hubris. I’m glad of it. I suppose I am glad because I work for a company that knows the difference and tends to put their weight behind it. Sure, we have some applications that are neither artificial nor intelligent, but we own up to the ones that are data and machine learning, and we boast about the ones that have weight to throw around. And that is fun and ambitious.

So I enjoy rolling up my sleeves to explore the ways that Generative AI might improve my work, and I enjoy tossing out the ways that it is a big, fat dud. So let’s look at the four ways I think it might actually improve what I do.

Drafting

First drafts are the things that take up the bulk of any writer’s time, whether tech writer or fiction writer. We know what it is that we want to say, we just aren’t sure how to get started. It’s not writer’s block per se, it’s just the words in our brains don’t spill out on to the page as quickly as we’d like or as smoothly as they should. Our years of training are well suited to editing and refining, which we are likely to have already begun in our heads. It’s the typing that can be painful because it simply isn’t as fast as our thought processes.

But a Generative AI tool is as fast. Faster, even. If we can spin up a good prompt, we can get some of the process started, and that is often enough to grease the wheels and we can take it from there.

Most likely the way we will be able to effectively harness what Gen AI really has to offer is to become adept at crafting and refining the prompts to get us started. I began writing chapters of my book recently by asking ChatGPT to help me organize the table of contents, then I asked it to revise that TOC because it wasn’t quite the way I liked it. The actual TOC looks nothing like it did when good ol’ AI first started it, but what was nice is that it gave me liftoff. I knew in my head what I wanted to do, but the way my creative brain was working was to think of the book as the whole, not its parts. That is awful for a writer. As the saying goes, “you can’t boil the ocean.” Indeed you can’t. And while AI wrote not a single word of this post, that’s because I have been able to think of its component parts. With my book, I was thinking of the whole thing, start to finish, and I needed a hand in visualizing what the chapters might look like. By asking AI to help me out with that, I was able to think of the pieces rather than the whole. It was only then that I could sit down and begin to write.

With that in mind, we as creators will be able to ask Gen AI not to write for us, but to draft for us, so that we can get out of the muck that is stuck in our brains and begin to refine and edit and revise after the foundation is laid. What is left behind as detritus will be much like what we left behind us when we were drafting ourselves – an unrecognizable skeleton of tossed aside word salads. It requires our fine touch to render the work useful and beautiful. Gen AI will have helped us get there faster, much the same way moving from horse to car allowed us to move from place to place more quickly, too.

Automating Q&A

As a tech writer, I cannot even begin to tell you how many times I have been asked to write an FAQ section for documentation.

My answer to this request is always the same. I will not.

I will not write an FAQ because if there are frequently asked questions, I should answer those within the documentation. Sheesh!

And yet.

There remain some questions that indeed, users will face time and again that are unlikely to be answered in the documentation. I get it. No matter how much of a purist I am, I understand that there are frequently asked questions that need frequent answers.

So a technical writer can collate those questions and help develop the chatbot that integrates with a product’s or company’s knowledge repository to answer those repetitive questions effectively. This bot can instantly provide responses in a way that no live writer could, through a call-and-response mechanism that is smoother than static documentation. By leveraging AI, we can ask our tools to ingest data and interpret our users’ needs and provide output that is both relevant and accurate. This can enhance the user’s experience by responding immediately whereas a human might require time to look something up, or might be off-hours or otherwise detained.

AI-powered chatbots are efficient, interactive, and fast. But they serve only after technical writers feed them all they need in terms of information. It’s vital to remember that our AI tools are only as good as the data they are given to start with.

Data

Technical writers will also be very well served by the data that AI can give us. Back when I was in graduate school, we worked very hard to manually enter volumes of information to build dictionaries of strings of phrases and what they meant in general syntax. It was difficult and time consuming. Today, though, thanks to AI-powered tools, we could have completed that project in a fraction of the time.

How AI data will benefit tech writers is that it will allow us to gather truly valuable insights into our users’ behaviors and we can stop making what we once knew were educated guesses about their pathways. Tools we have now measure user engagement, search pattern behaviors, and even the effectiveness of our content through click rates, bounce patterns, andmore, and they serve it all up in nice, tidy numbers. We can use this to optimize our content and identify the gaps we see and close them quickly.

Leveraging analytics data allows tech writers now to focus on the content our users access often, the content that interests them the most, and the keywords they search – and do or do not find – with greatest success. Plus, we can now see just what stymies our users and all of this will empower us to create the most targeted content that will greatly improve the user experience.

Optimization

More than just a buzzword, content optimization is probably the most powerful benefit of AI-enabled tech writing. Asking a good AI tool to analyze technical documentation to provide feedback about readability against a style guide and structural rules is probably the best thing we could ask for. Sure, we’ve got things like grammarly and acrolinx to do spot-checking. That’s all well and good. But now AI can help us enhance accessibility, it can help us tailor content for specific audiences, it can allow or disallow entire phrases and terms. We can advance our proofreading capabilities far more than we could before by loading in custom dictionaries and guides.

Tools like grammarly are basic, but with advancing NLP processing tools, the arsenal we have just grows. We can pass our work through a domain-specific tool that offers a profession-specific set of guidelines and lets us examine with a microscope things like acronyms, codes, and more.

The time savings there is not perfect, of course. We’ll still need to copyedit. But imagine, if you will, that every first or second pass of all of our text now is done in mere seconds. All typos are caught by AI so that we can clean up and polish with an editor’s eye not just a proofreader’s.

Sit back with a cup of coffee and really read, not just grab a pencil and mark up a piece of paper the way we used to.

My, that’s nice.

I’m Your Writer, Not Your Everything

Or, Hey there, Have You Seen My SME?

I couldn’t even think of a cool graphic or photo to go with this, so here we are, graphic-less. That’s probably good, because I am not starting off the year on a happy, optimistic note to be honest.

Let’s get one thing clear. I am a SME. I am absolutely, without a doubt a subject matter expert. One hundred per cent. Although I spend most of my time writing about a software product in the area of clinical trials data analytics, I am decidedly not an expert in clinical trials data analytics. Nor was I hired to be that.

I am a subject matter expert in technical writing, in grammar and syntax.

I am supposed to be just that. I deliver on that promise every day. I rarely make an error in my delivery of high-quality content. I know what readers need and how they need it to be organized. I understand where the reader’s eye is likely to go and what concepts should be placed where. More importantly, I can spot a typo in difficult language and if I am unfamiliar with a term I know where to go to look it up, when to insist on that word, and when to choose another. I build dictionaries and document frameworks. I organize tables of information. My spelling is almost perfect and so is my grammar.

What I am not is a subject matter expert in data analytics. Do you want to know a secret? I was not a subject matter expert in mainframe banking software when I was a technical writer for my former company, either. And I was not a subject matter expert in cybersecurity when I worked in that field. Are you sensing a pattern or is it just me?

Now is the moment when I sigh.

The burden on technical writers is becoming ever steeper. Our teams are becoming thinner and our demands are becoming heavier. We have always carried the weight of justifying our positions when budgets tighten, showing our value since our deliverable often doesn’t bring with it a 1:1 ROI, and showing mid- and upper-leadership that continued investment in upskilling is essential. As the asks of today’s software teams become greater and the speed with which we deliver becomes faster, demonstrating those values seems to be tougher and tougher.

I generally work with great people and teams and on balance the work that I do is seen as necessary if not critical to the end product. But more and more I learn of teams that want their tech writers to be so fully embedded in the end-to-end development that the lines between coder and ux designer and writer are not just comfortably blurred, they are erased.

At the end of the day, all I know for certain is this: I will remain a subject matter expert in grammar, syntax, and spelling and I will feel quite comfortable in that area. When I am called upon to be a soup to nuts pro in a complex piece of software, I think I’ll start asking my development teams to explain to me the differences between a gerund and a participle, and to recommend when I should use each in the installation manual I am working on today.

Singing a New Tune in AI – Prompt Tuning

We are all well aware that AI is the hottest topic everywhere. You couldn’t turn around in 2023 without hearing someone talk about it, even if they didn’t know what the heck it was, or is. People were excited, or afraid, or some healthy combination of both.

From developers and engineers to kids and grandmas, everyone wanted to know a thing or two about AI and what it can or cannot do. In my line of work, people were either certain it would take away all of our jobs or certain that it was the pathway to thousands of new jobs.

Naturally I can’t say for certain what the future holds for us as tech writers, but I can say this – we as human beings are awful at predicting what new technologies can do. We nearly always get it wrong.

When the television first arrived, there were far more who claimed it was a fad than those who thought it would become a staple of our lives. The general consensus was that it was a mere flash in the pan, and it would never last more than a few years. People simply couldn’t believe that a square that brought images into our homes would become a thing that eventually brought those images to us in every room of our homes, twenty four hours a day, offering news and entertainment, delivering everything we needed all day and all night. They couldn’t fathom that televisions would be so crystal clear and so inexpensive that every holiday season the purchase of a bigger, better, flatter, thinner television would be a mere afterthought.

And yet here we are.

So now that we’ve got that out of the way, on to total world domination!

But seriously.

If you aren’t already using AI, or at least Gen AI in the form of something like Chat GPT, where are you, even? At least have a little play around with the thing. Ask it to write a haiku. Let it make an outline for your next presentation. Geez, it’s not the enemy.

In fact, it’s so much not the enemy that it can help you outline your book (like I’ve done), revise a paragraph (like I’ve done), or tweak your speech (like I have done many, many times). The only thing you really need to understand here is that you are, indeed, smarter than the LLM. Well, mostly.

The LLM, or large language model, does have access to a significantly grander corpus of text than you can recall at any given moment. That’s why you are less likely to win on Jeopardy than if you were to compete against it. It’s also why it might be true that an LLM competitor might make some stuff up, or fill in some fuzzy details if you ask it to write a cute story about your uncle Jeffrey for the annual Holiday story-off. (What? Your family does not actually have an annual story-off? Well, get crackin’ because those are truly fun times…fun times…). The LLM knows nothing specific about your uncle Jeffrey, but does know a fair bit about, say, the functioning of a carburetor if you need to draft a paragraph about that.

The very, very human part is that you must have expertise in how to “tune” the prompt you offer to the LLM in the first place. And the second place. And the third place!

Prompt tuning is a technique that allows you to adapt LLMs to new tasks by training a small number of parameters. The prompt text is added to guide the LLM towards the output you want, and has gained quite a lot of attention in the LLM world because it is both efficient and flexible. So let’s talk more specifically about what it is, and what it does.

Prompt tuning offers a more efficient approach when compared to fine tuning entirety of the LLM. This results in faster adaptation as you move along. Second, it’s flexible in that you can apply tuning to a wide variety of tasks including NLP (natural language processing), image classification, and even generating code. With prompt tuning, you can inspect the parameters of your prompt to better understand how the LLM is guided towards the intended outputs. This helps us to understand how the model is making decisions along the path.

The biggest obstacle when getting started is probably designing an effective prompt at the outset. To design an effective prompt, it is vital to consider the context and structure of the language in the first place. You must imagine a plethora of considerations before just plugging in a prompt willy-nilly, hoping to cover a lot of territory. Writing an overly complex prompt in hopes of winnowing it down later might seem like a good idea, but in reality what you’ll get is a lot of confusion, resulting in more work for yourself and less efficiency for the LLM.

For example, if you work for a dress designer that creates clothing for petite women and you want to gather specific insights about waist size, but don’t want irrelevant details like shoulder width or arm length and competing companies, you might try writing a prompt to gather information. The challenge is to write a broad enough prompt, asking the AI model for information about your focus area (petite dresses), while filtering out information that is unrelated and avoiding details about competitors in the field.

Good Prompt/Bad Prompt

Bad prompt: “Tell me everything about petite women’s dresses, sizes 0 through 6, 4 feet tall to 5 feet 4 inches, 95 lbs to 125 lbs, slender build by American and European designers, and their products XYZ, made in ABC countries from X and Y materials.”

This prompt covers too many facets and is too long and complex for the model to return valuable information or to handle efficiently. IT may not understand the nuances with so many variables.

A better prompt: “Give me insights about petite women’s dresses. Focus on sizes 0 to 6, thin body, without focusing on specific designers or fabrics.”

In the latter example, you are concise and explicit, while requesting information about your area of interest, setting clear boundaries (no focus on designers or fabrics), and making it easier for the model to filter.

Even with the second prompt, there is the risk of something called “overfitting,” which is too large or too specific. This will lead you to refine the prompt to add or remove detail. Overfitting can lead to generalization or added detail, depending on which direction you need to modify.

You can begin a prompt tune with something like “Tell me about petite dresses. Provide information about sizes and fit.” It is then possible to add levels of detail that the LLM may add so that you can refine the parameters as the LLM learns the context you seek.

For example, “Tell me about petite dresses and their common characteristics.” This allows you to scale the prompt to understand the training data available, its accuracy, and to efficiently adapt your prompt without risking hallucination.

Overcoming Tuning Challenges

Although it can seem complex to train a model this way, it gets easier and easier. Trust me on this. There are a few simple steps to follow, and you’ll get there in no time.

  1. Identify the primary request. What is the most important piece of information you need from the model?
  2. Break it into small bites. If your initial prompt contains multiple parts or requests, break it into smaller components. Each of those components should address only one specific task.
  3. Prioritize. Identify which pieces of information are most important and which are secondary. Focus on the essential details in the primary prompt.
  4. Clarity is key. Avoid jargon or ambiguity, and definitely avoid overly technical language.
  5. As Strunk and White say, “omit needless words.” Any unnecessary context is just that – unnecessary.
  6. Avoid double negatives. Complex negations confuse the model. Use positive language to say what you want.
  7. Specify constraints. If you have specific constraints, such as avoiding certain references, state those clearly in the prompt.
  8. Human-test. Ask a person to see if what you wrote is clear. We can get pretty myopic about these things!

The TL;DR

Prompt tuning is all about making LLMs behave better on specific tasks. Creating soft prompts to interact with them is the starting point to what will be an evolving process and quickly teaching them to adapt and learn, which is what we want overall. The point of AI is to eliminate redundancies to allow us, the humans, to perform the tasks we enjoy and to be truly creative.

Prompt tuning is not without its challenges and limitations, as with anything. I could get into the really deep stuff here, but this is a blog with a beer pun in it, so I just won’t. Generally speaking (and that is what I do here), prompt tuning is a very powerful tool to improve the performance of LLMs on very specific (not general) tasks. We need to be aware of the challenges associated with it, like the hill we climb with interpretability, and the reality that organizations that need to fine-tune a whole lot should probably look deeply at vector databases and pipelines. That, my friends, I will leave to folks far smarter than I.

Cheers!

Optimize! They said. It’ll be fun! They said.

Photo by Tianyi Ma on Unsplash.

Now that all of us write web-based content and can’t even SEE print matter in the rearview mirror, we’ve adapted (or started to adapt) to a whole different set of challenges. I used to organize documentation for release in a binder, so I had to think about tab structures and indeces and a list of other layout technicalities that would make my precious topics finable.

Today, though, I must lean in to Content Optimization. Sounds catchy, doesn’t it? Slick. Advertorial. In some ways, it is. But mostly it’s about the same thing: how to find the gorgeous stuff I’ve written, and essentially how to make that the best end-user experience it can be.

Why should we optimize in the first place? Half of us don’t know for sure what that word means, even. Let’s set some parameters:

Optimized content is written at the right reading level and tone. It is translatable if needed. It is consistent and reliable, not working too hard to say the same thing in two or three ways. It is balanced – between grammatical correctness and ease of reading. That’s pretty much it!

The fun thing about writing technical documentation is that we can optimize before, during, or after composing our prose. As we create new doc, we can roll along just writing stuff the way we want – so long as we go back later to clean it up! Or, we can vigorously adopt optimization principles step by step so that when it’s time to edit, we’ve got a pretty good draft already.

I would venture to say that the primary goal of content optimization is seeing to it that your documentation reaches the largest possible audience within your target. Nobody cares if I write an article all about fashion and the only people who see it are auto mechanics who wear uniforms. See what I mean?

I would also say that making sure your content is visible, especially to web-crawlers, is an important aspect of optimization. Consider the beautiful website that never shows up in Google Search – that writer and designer worked hard on content, but can’t get it off the ground! What a shame.

We know that great content attracts readers no matter what, but what IS “great content?”

For starters, write clearly and relatably with your reader in mind. That is step one no matter when or what you are writing. When my oldest son started college, I reminded him often that the most important factor in his college papers was that his professors were the audience. They were the ones to please, and no one else. Know your audience should be a phrase posted by every content creators desk.

Keep writing NEW content. If things get stale, you have missed the point of optimization altogether. Even if none of the information has changed, good writer-editors will revise again and again over time. It’s just good practice.

Organize content, not unlike the “olden days” when we organized a TOC and an index. Thoughtfully preparing well-organized content is at the heart of a pleasant experience for end users.

Don’t forget images! When we incorporate images and other media into our online content but do not optimize those elements, we’ve lost an important tool. Using title tags, descriptions, alt text, and more can make sure that the images you’ve worked to capture are useful and visible.

Don’t just write for search. All too often, in the pursuit of clicks, writers think too much about SEO and they lose the natural, organic flow of writing and reading. Consumers are more savvy than ever, especially with web-based content, and they catch on quickly if your goal is just to be at the top of the search engine, while you overlook the enjoyment of finding content you need!

Optimization is all about making the experience easy and smooth for all who use the content you create. If we go at it from that point of view, it actually IS fun…like they said.

‘Appropriate Use’

And Other Strange Terms in Generative AI

Google has for quite some time now been the de facto word in all things web. Sure, Microsoft and Bing gave it a shot, but never quite broke through the hefty barriers set by behemoth Google. So when the folks at Google set out to put some guardrails around AI generated content, the world paid attention.

Google wrote search guidance about AI-generated content, focusing on ‘appropriateness’ rather than attribution. Their stance is that automation has long been used to generate content, and that AI can in fact assist in appreciable ways. One of the most interesting bits about their policy is noting that it isn’t just some bot that can create propaganda or distribute misinformation. In fact, they are quick to point out the very human-ness in that capability. Since the beginning of information dissemination there’s been the capacity to distribute falsehood, after all.

Further, Google asserts that AI-generated content is given no search privilege over any other generated content. And yet, despite this assertion, we know that AI tools can be asked via well-designed queries to write content that is specifically designed to tick all of the SEO boxes, thus potentially rocketing it upward in search efforts. The human brain cannot log and file all of the best potential search terms. We just don’t have that sort of computing power. But AI does. And it has it in spades.

Creating relevant, easily findable content is the whole effort for tech writers. Our jobs depend on being able to place the content users need where the content consumers expect to find it. Many of us have trained for years to scratch the surface of this need, and most of us continue to refine that ability by monitoring our users’ journeys and mapping their pathways. But now AI can do this at a speed we never could. We rely on analytics to tell us what to write where.

Moreover, as humans we rely on our own inherent creativity to design engaging and timely documentation. Every single writer I have ever known, including myself of course, has experienced a degree of “writer’s block,” sometimes even when the prompt is clear and direct. It’s tough to just get started. But when a program has access to all of the ideas ever written (more or less), that block is easy to dismantle. But when we rely on AI to generate the basis for our content, even if we intend to polish, edit, and curate that content, where does the authorship belong? Is it ‘appropriate use’ to place an author byline as the sole creator if a large language model is the genesis of the work? Google’s guidance is merely to “make clear to readers when AI is part of the content creation process.” Their clarification is…unclear.

Google does recommend, in it appropriate use guidance, to remain focused on the ‘why’ more than the ‘how.’ What is it that we, as content generators, are trying to achieve in our writing? We go back to the audience and purpose more than the mechanics and we’ll be fine. Staying in tune with the reason or reasons for our writing will keep us in line with all appropriate use guidelines. For now. If we are writing merely for clicks or views, we’ve lost our way. If we continue to write for user ease and edification, well okay then.

Even Google acknowledges that Trust is at the epicenter of their E-E-A-T guidelines (experience, expertise, authoritativeness, and trustworthiness) which is the basis of their relevant content rankings. AI could certainly create content with a high level of expertise, noticeable experience, and authoritativeness, but we’ve found that the trustworthiness is suspect.

For now, our ‘Appropriate Use’ likely remains in the domain of those of us with conscience, which AI notably lacks. Avoiding content created merely for top rankings still nets humans, and human readers, the desired end result, even if it doesn’t make the top of the list.

Appropriate is not always Popular.

Why the Humanities Matter in STEM

Photo credit: Prateek Katyal, 2023.

A 2017 article in the Washington Post discussed how now, in the age of big data and STEM (Science, Technology, Engineering, and Mathematics), liberal arts and humanities degrees are perceived as far less valuable in the marketplace. I saw the same opinion held strong at both universities where I taught English. Many, many students believed wholeheartedly that the only thing they could do with a degree in English is teach.

I was hard-pressed to convince them otherwise since I was, in fact, teaching.

The Post article goes on to argue, however, for abundant evidence that humanities and liberal arts degrees are far from useless.

When I started graduate school in 2007 at university that beautifully balances the arts and sciences (shout out to you, Carnegie Mellon!), my advisor recommended I take “the Rhetoric of Science.” I meekly informed her that I wasn’t really into science. I thought it would be a bad fit, that I would not fare well and my resulting grade would reveal my lack of interest. She pressed, saying there was a great deal to learn in the class and that it wasn’t “scienc-ey.”

She was absolutely right. I was fascinated from the start. The course focused on science as argument, science as rebuttal, but most of all science as persuasive tool. Or, at least the persuasiveness came from how we talk and write about science. My seminar paper, one of which I remain proud, was titled: “The Slut Shot. Girls, Gardasil, and Godliness.” I got an A in the class, but more importantly I learned the fortified connection between language and science.

The National Academies of Sciences, Engineering, and Medicine urges a return to a broader conception of how to prepare students for a career in STEM. Arguing that the hyper-focus on specialization in college curricula is doing more harm than good, they argue that broad-based knowledge and examination of the humanities leads to better scientist. There is certainly the goal among academics to make students more employable upon graduation, and yet there is consensus that exposure to humanities is a net benefit.

The challenge is that there’s no data. Or, limited data anyway. The value of an Art History course or a Poetry Workshop at university is hard to measure against the quantifiable exam scores often produced in a Chemistry or Statistics class.

In a weak economy, it’s easy to point to certifications and licenses over the emotional intelligence gained by reading Fitzgerald or Dickinson. We find, though, that students (and later employees) who rely wholly on the confidence that science and technology provide answers, viewing it with an uncritical belief that solutions to all things lie in the technology – well, those beliefs are coming up short. Adherence to the power of science as the ultimate truth provides little guidance in the realm of real-world experiences.

In short, not all problems are tidy ones.

After all, being able to communicate scientific findings is the icing on the cake. We don’t get very far if we have results but do not know how to evangelize them.

In American universities right now, fewer than 5% of students major in the humanities. We’ve told them that’s no way to get a job. The more we learn about Sophocles, Plato, Kant, Freud, Welty, and others, the more prepared we are to take on life’s (and work’s) greatest challenges. It is precisely because the humanities are subversive that we need to keep them at the heart of the curriculum. Philosophical, literary, and even spiritual works are what pick at the underpinnings of every political, technological, and scientific belief.

While science clarifies and distills and teaches us a great deal about ourselves, the humanities remind us how easily we are fooled by science. The humanities remind us that although we are all humans, humans are each unique. Humans are unpredictable. Science is about answers and the humanities are about questions. Science is the what and the humanities are the why.

If we do our jobs well in the humanities, we will have generations to come of thinkers who question science, technology, engineering, and math.

And that is as it should be.

I welcome discussion about this or any other topic. I am happy to engage via comment or reply. Thanks for reading.

Med-Tech, Fin-Tech, and MarCom – Oh My!

Photo by Nick Fletcher.

The whole field of technical writing, or professional writing, seems to have expanded like a giant infinite balloon in the last decade. Where previously it was a specialty, now it’s an entire field complete with sub-specializations.

How cool is that?!

I told the story just the other day that when I graduated from high school, I knew I was off to college to major in English. It had always been my best subject, I love reading but I love writing more, and it was just the obvious choice. Except…I also asked for money instead of gifts because I was determined to buy my own computer. Other than some desktop publishing, I couldn’t envision what the two had in common, but I was connecting them somehow.

Had I only known then that I would spend my career as a technical writer, I probably would have gotten a much earlier start. I focused on essays and creative nonfiction, which I later taught until I discovered what I solidly believe is the best professional writing graduate program anywhere – at Carnegie Mellon. Indeed, the robotics and engineering monolith hosts an impressive writing program for students looking at Literary and Cultural Studies, Professional & Technical Writing, and Rhetoric. I opted for the last of the three and am happy with my choice, even though I landed a career in Prof & Tech.

Evangelizing this field is easy for me, even as it becomes more complicated. I can see clearly now that taking an Apple IIGS to college was the harbinger that I would eventually be a software writer. I work now for a major software company and love what I do.

But wait – there’s more. (Please say that in an infomercial voice. You won’t be sorry.)

I wrote proposals for federal-level contracts for a while. I taught Human-Computer Interaction. I edited science articles. The breadth of writing is not unique to me, and it was very helpful.

Because the company I work for delivers software solutions for medical clinical trials. Eureka! Again, that college freshman had zero idea that she could combine a love of writing, and interest in computers, and a genuine interest in science. Back then, the marriage of all three seemed impossible.

And yet…

As a technical writer starting out, it’s perhaps not so important to “find focus” in a given industry. However, once you decide you indeed want to produce professional documentation, specializing in an interest is helpful. There are so many areas to choose from that it’s nearly impossible to NOT find one that is interesting as well as challenging. I would not, for example, find deep satisfaction in writing installation manuals for gas pipelines. But someone does. Someone enjoys that very much. I participated in a review panel for a writing competition and my assigned document was an infant incubator (baby warmer) user manual to be read by nurses. I found the content to be expertly delivered, and yet I had no actual interest in what the device does or how to use it. Give me something about gene therapy research and predictive modeling? I am IN!

Some writers find that they are fascinated by banking, taxes, estate planning and so on – welcome to tech writing for loads and loads of financial applications from Turbo Tax to Betterment. The field is growing so rapidly that every investment tool, firm, and product needs a skilled writer. For those who find dollars and cents and amortization and net worth interesting it’s a huge category, and you can specialize in all sorts of ways. Someone who digs marketing but doesn’t want to be a marketer will find a spot in a real estate app, a travel tool, or even music software like iTunes. They all need documentation. Every. Single. One.

What about the folks who say the documentation is superfluous? While it may be true that an app like iTunes or Netflix is so intuitive that it doesn’t need user doc, the moment a user is stymied and needs an answer, that documentation is one thousand percent necessary.

I often talked with my students about the wide variety of uses for their writing skills, many of which would leave plenty of time for creating poetry, fiction, and the like. Heck, even I write memoir in my spare time.

But it’s Sci-tech, Med-tech, and Bio-tech that butter my bread. If you find any area that interests you, I can guarantee there’s a technical document somewhere for you to write and edit, and it’s all about that field.

Work-Life Balancing That Works

Image courtesy of Yuki Nakamura on Unsplash.

This week is the Cherry Blossom Festival in Washington, DC. It’s less than an hour by train from my house, and is arguably the prettiest harbinger of spring in the mid-Atlantic corridor. Saturdays and Sundays in the limited-run showing of the more than 3,000 cherry blossom trees are a chaotic influx of visitors from around the globe. Busy is a deep understatement. Crowded doesn’t begin to describe.

A fair-weather weekday, though? That provides nearly perfect viewing conditions for the gorgeous 1912 gift from Tokyo.

Alas. That would interrupt a work day. If I took the 2pm train to DC and wandered about the tidal basin for a couple of hours, the earliest I could be back home would be, say, seven p.m. assuming I stop for a bite to eat and don’t rush to ride the train home at 5pm with all of the commuters.

And yet – I’ll likely do it. I’ll feel no guilt about stepping away from my desk at 2, because it’s very likely I’ll sign back on at 7 or 7:30, and will have started my work day at 6:30 a.m. as usual anyway. I’ve been known to crank out some pretty great work at 10 p.m., or to manage some very focus-heavy work before 7 a.m. EST. I very frequently get some good writing done on Sunday morning, or a rainy Saturday afternoon.

Sometimes the 9-to-5 model of work doesn’t work.

Even before the pandemic, strict adherence to a 9-to-5 schedule was on its way out of favor. The onset of COVID-19 made it nearly obsolete not because workers were taking more time for themselves, but because working from home allowed them to take less. Throughout the pandemic, I’ve been working for companies whose workforces span international time zones, sitting on multiple continents. Working a traditional office schedule just no longer seemed pertinent.

There are days when I wake up at 5 a.m. and am energized enough to get started. There are other days when I prioritize going to the gym in the morning, meaning I won’t be at my desk until 8:30 or so. I am a fairly morning-centric person and I like the time to work without disruption from team members with questions or tasks. Working a bit on the weekend allows me the same kind of freedom from slack messages and time sensitive emails. Focus is good for this writer.

I’m not here to brag about my weekend work ethic, I assure you.

I’m here to point out that if you are super-efficient at 8 p.m. after you’ve put the kids to bed and are beginning to settle your mind into tasks you can handle, then by all means work at 8 p.m. But if you choose to do that, don’t feel tethered to your desk from 9 a.m. the whole way through, because that is where burnout happens. Burnout doesn’t come from logging time on a Saturday or before the rooster crows. It happens from feeling the need to be present at your desk even at your lowest capacity. If there are times of day that you are not productive, it’s likely those are the times you should go for a walk, make a grocery run, meditate, read a chapter from that book on your nightstand. You get what I’m saying.

Shed the idea that opening your laptop at 10 p.m. is a sign of overwork. If you provide room for “me time” when it is best for you, then you can also provide “work time” when you are at your peak.

I get it, sometimes you simply must be present for the typical work day to answer emails, attend meetings, and all of those necessary elements of our jobs. But there are other times when you can totally work “outside the box,” and not only should you, but you should also then take advantage of offsetting your time.

Take some time to smell the roses.

Or the cherry blossoms.

Minimum Viable Documentation: the Bare Minimum Doesn’t Have to be Bare.

Do less with more.

Practice minimalism.

Do “documentation triage.”

All of these are concepts we’ve heard about, and have been tasked with understanding and implementing across our documentation practices. But what are they and why do they matter? And how will creating “Minimum Viable Documentation” impact what we do and how we do it?

We learned ages ago in the software development world that “perfect is the enemy of done.” That applies to writing as well. We can move participles and conjunctions around all day and still never achieve perfection. As a professor, I told every single one of my students, usually on day one, that they would never receive a 100% on any paper they submitted to me. I wholeheartedly believe that there is always room to improve. I think the best writers throughout the history of time would agree with me. As a teaching tool, I often used e. b. white’s “Once More to the Lake” as an example of how revisiting a piece of writing many years later can fundamentally shift it to the better without trying to change it in tone or style whatsoever.

So how do we create documentation that is good enough without sacrificing our standards?

The first step, according to esteemed technical writer Neal Kaplan is to “prioritize ruthlessly.” It’s vital to look at what actually needs to be documented, and focus on that. The rest is, as they say, gravy.

When we are early in our writing careers, and sometimes just when we are early in our writing projects, we think it is important to document everything. No step or function should be relegated to the trash heap. We fail to plan, and therefore plan to fail. When we look at documentation as a broad-sweeping need for users, we miss the point. We lament that no one reads the documentation, but we keep writing it. Why? Are we hoping users will do an about-face? They won’t. Ao as my high school English teacher reminded us time and again: plan your work and work your plan.

That planning is what Kaplan calls triage. I just call it good practice.

  1. Start planning long before you start writing.

2. Give every task an estimated level of effort – even if it’s a guess, start guessing.

3. Use documentation architecture – design your plan, and plan to grow.

4. Stand by your plan,but be open to changing it.

See how not all of those numbered items are aligned? I chose that architecture because the first one is vital, the others then follow. Plan. Plan. Plan. They are each important, though. Following these 4 will result in documentation that gets the job done, doesn’t leave bare spots, but isn’t full of extra bells and whistles.

You’d never hire a contractor to work on your house without an estimated level of effort. You want to know how long that project will take, how difficult it will be. Your contractor lets you know it will be a couple of days, or a couple of weeks. It is an estimate and it is not a firm commitment, but it sort of time-boxes the work to be done. It’s rarely spot-on. You might have an architect that shows you how fantastic a skylight would be, but once your contractor starts the work, he tells you that will be a challenge to complete based on the roof, the seal, whatever. So you nix the skylight.

Your contractor takes a dive into the work and then recognizes that perhaps you would prefer the sink on the other side of the room, or maybe you want a different fixture than the one you saw in the store. You can put your foot down based on time, cost, and aesthetics. It may be that the extra time required to purchase a new fixture will change the look of the room enough that the pivot was worth it.

On the other hand, maybe the new fixture is out of budget or will take too long to install. It’s something you can see having installed in a year or two, but it isn’t necessary right now. Okay, so you know that down the road you have some more work to do, but getting the standard fixture installed keeps you on time, on budget, and your rom is usable.

Usable.

That is the key word in all of this. Usable.

Our “bare minimum” is hardly bare when our documentation is usable. Minimum viable documentation is choosing to follow the design plan your architect and contractor gave you, but adding all of the decorative touches later. You’ll have a fully functioning and attractive room with the key elements. You can add the flourish later, if you add it at all.

I’ve extended this metaphor about as far as I want to, and if I continue to write I will violate the basic principles of conciseness. Tell your teams that Minimum Viable Documentation is not the writing equivalent of a rough draft. It is the equivalent of writing a 2-page paper when you recognize that a dissertation is unnecessary. You can be sure that every comma, bullet, and number is correct if you write briefly. The viable minimum is so much better than the bare minimum, and worlds better than the alternative.