Traditional tech writing, new tech writing


#1

Hoping to continue a twitter conversation with @mikejang, Laura Lemay (@lemay on Twitter), and all comers here. My version of the twitter backstory (others’ may vary):

TL;DR version: Laura tweeted some cool stuff about how it seems that traditional definitions of tech writing are dying out but the value that they add is being lost in the process, and needs to be brought back. A few of us continued the twitter conversation until it got out of hand, and Mike suggested we move it over here.

The I-tend-to-write-epics version:
Toward the end of day 2 of the conference, I did one of my only-occasional-during-the-conference checkins with twitter, to find a fantastic tweetstream from Laura, who I remembered from my early days as a tech writer as someone whose words are Worth Paying Attention To. I thought, this is great stuff, I must favorite so I can figure out how to reply (later) – only to realize at the end (which was really the beginning), that she was tweeting from Write The Docs. Too late in the day for me to figure out how to find her, but we sort of continued to discuss definitions and situations on twitter, until <see_above_content_reuse>.

Here are Laura’s working definitions of traditional tech writing and new tech writing (please note the “old” in the topic title is my infelicity):

http://techwhirl.com/what-is-technical-writing/ (for the traditional)

The new:

(only one of Laura’s great tweets on the topic - go read them all):
New tech writing: ad-hoc tools, process, structure, small numbers of writers integrated with engr using engr tools.


Traditional v. New Tech Writing, v2
What conferences do you like to attend?
#2

Gosh, Laura was there? I would have tried to seek her out too. Before I started writing about OSes, I listened to her on a book tour stop at some B&N around Seattle.

I think this tweet brings up a key question:

@lemay @WriteTheDocsPDX The catch is that a tech writer with dev skills has a lot more opportunity (pay/influence) as a dev.

— laura lemay (@lemay) May 21, 2015

If we as documentarians want to write for Devs, don’t we need Dev skills?


#3

I’ve been reading a bit around the interwebs, trying to get a better historical perspective. I’m not ready to write up this stuff more formally, but I found some of my assumptions about the history of technical writing and formal programs organized around it challenged by this:

… and I also thought it provided a useful frame for the techwri-l definition of technical writing.


#4

“we changed the department’s name from Technical Communication
to Human Centered Design and Engineering”

Is that related to our focus on (not related to JIRA) user story-driven docs? Was it also a preview of the current decline of the STC?

(If you’re looking for historical info, I think Amelia Abreu talked about it at WTD 2014, with ref to http://en.wikipedia.org/wiki/Suzanne_Briet )


#5

Whoops. I realized just now I was deeply unclear on twitter – I was not at Write the Docs. (I couldn’t get my act together, had a lot to do that week, long story, boring.) I was just following along on twitter via the #writethedocs hashtag – tons of livetweeters, lots of good info – and chimed in with my thoughts toward the end. Sorry to give the wrong impression!

I storified all the tweets in the convo here:

I’m actually conflicted about the value of traditional tech writers (even though I am one; I’ve been a tech writer (staff, contract, and freelance) my entire career). The tech writing profession can often seem stodgy and hidebound, and as I noted in my tweets there can be issues with a tech writing organization being a separate org from engineering.

BUT on the other hand traditional tech writing has a huge body of knowledge and research into how people learn, and read, and use documentation, which I think is getting lost with the new tech writing, where other roles are doing the writing, or writers without a TW background are being hired into TW roles. How to structure technical documents, how to write procedures, the differences between overview/task/reference docs – all of this is well-traveled ground amongst technical writers. And traditional tech writing is well ahead of the new tech writing when it comes to internationalization, content reuse, and other issues that you don’t generally encounter until you have a very large or mature product.

I’m not so much calling for a return to traditional tech writing, but I think there could be a lot more cross-pollenization going on between our two communities. Maybe I am the bee. :slight_smile:


#6

I have to laugh. I’ve been wrestling with a blog post about this stuff. It’s been on my mind for longer than this year’s Write The Docs or the tweet storm, but they inspired me to try again. Alas, I am long-winded, and all too often deeply confused in my own writing, at least in the initial drafts.

Short version: Laura says in her final three paragraphs quite perfectly what I’ve been trying to say in many more paragraphs/planned series of posts/freakin’ monograph. Thank you, and I couldn’t agree more!

(Wrong impression? nah – I mostly thought, dang, it was too late to find you at the conference … And it’s pretty cool that the twitters gave you some sort of virtual attendance. Never mind the fact that your tweets were dead on target. Although I’d like to think that Write The Docs is also part of the swarming hive …)


#7

Hi, Joao Fernandes here.
I’ve presented at write the docs this year, and I feel I’m on the “new tech writing” field. Whatever that means :laughing:.

I’m glad I found this discussion. I was following on twitter all the discussions with the #writethedocs tag, but I seem to have missed this one.
After reading @lemay 's story line, I think I somewhat understood her definition of “traditional tech writing”. Also, one of my colleagues has lots of experience on the field, and I think he clearly fits on the “traditional tech writer” definition. So I can experience in first hand and on a daily basis the clash between traditional and new tech writing mindsets.

I’ll try to explain some of my core values as a “new tech writer”, and will then explain why I feel they are most adequate, specially as you try to do continuous deployment.
I’ll then try to argue on some points that @lemay on her tweet storyline tells that “traditional tech writing” got better results, and why I think “new tech writing” can achieve results that are just as good, or even better.

I value:

  • Individuals and interactions over highly structured processes. This means that I don’t mind tweaking my documentation process, or having ad-hoc processes, as long as I’m able to give meaningful feedback to the development teams and shipping documentation early and often. I feel that “traditional” tech writing was too much focused on processes and not so much focused on the end-user.
  • Some documentation to perfect documentation that never ships. I feel that “traditional” tech writing had a huge focus on creating extensive documentation, even if it took forever to be shipped. Since most of my documentation is on the web I can ship often, get feedback as any other part of our product, and iterate with the help of our users.
  • Responding to change, instead of sticking to a plan that was made when I had few information. Again I feel that “traditional” tech writing was so much focused on process and plans. The focus should be on the product and your users, and not so much on your own plans.
  • Giving users the information they care about. And avoid creating documentation just for the sake of completeness, specially if I’ve got metrics telling me that users don’t read that piece of documentation.

Some of these were probably the reason why “traditional” tech writing was so distant from the engineering, and as a side effect, getting information from the development team was a really difficult task.

I agree that having smaller teams, and sometimes ad-hoc processes might make it seam that it’s difficult to create a mentorship culture, where knowledge and best practices are passed from seniors to juniors. But I don’t think this is necessarily true.
For instance, “traditional” tech writing had a lot of focus on following best practices and style guides, so most times “mentoring” was just a misleading synonym for “go read the style guide before writing anything”.
With “new” tech writing, if I’ve got a small team I don’t feel the need for having style guides. And that forces me to do some real mentoring. I really need to sit, read, review, and share honest feedback with junior team members, if I hope to have consistent docs.

And about the career path and progression, I only see new opportunities emerging. As with “old” development, you could get away only knowing a single programming language, “new” development requires a more open approach and that you’re willing to learn better tools for your job.
I think the same is happening to tech writing. The barrier of product and documentation is getting more fuzzy, so you’ll need to acquire new skills to tackle new challenges.

I hope my view is a meaningful contribution to the discussion :smile: I’m continuing to learn so much, even after the conference has ended.


Traditional v. New Tech Writing, v2
#8

Joao, great contribution! If I’m reading correctly, your definition of “new tech writing” (I say “documentarian”) follows Agile principles – and is not tied to the Agile process.


#9

Spot on Mike.

I follow a set of principles that I feel deliver value to my users. My core values are very much aligned with the Agile manifesto (but I’ve got some others).

About Agile processes… at my company we use a mix of SCRUM and KANBAN, but my view is that there isn’t a right way of doing agile. So you need to tweak your processes until you find the ones that make you fast and productive.

As an example, if you’re doing daily SCRUM meetings, don’t understand why, and can’t extract any value from them, then you’re not being agile (in the pure sense of the word). You are just mindlessly following something that’s making you waste time.


#10

Thanks for the link! It was fun to read Judy’s history of the department.

I’m new to the forum, but I’ve been in and out of the UW’s TC/HCDE department since 2007. During that time, I’ve watched the department evolve from inside and out. I got my MS in 2009 when they changed the name so I had the option to choose between an MS in TC or an MS in HCDE. I chose the latter because it seemed bigger, as in broader and a better representation of the program’s scope. I thought it was slightly ironic that I took very few “technical writing” courses for my MS degree.

I went back in a year later to start work on a PhD (in HCDE) and I’ll be “out” again (graduating), soon. Looking over the work of recent PhD graduates from the department, my dissertation is one of the few (the only?) to actually study some sort of [what I would characterize as traditional] technical communication (API documentation, to be specific). The recent dissertations also reflect the broader focus of the department (which, by the way, I think is very cool).

All of this is to say that TC/TW isn’t what it used to be. It’s much bigger, these days. More outlets, more publishing formats, more audiences, more levels of audience involvement and interaction.

Exciting times ahead!


#11

Bob, as a onetime academic historian, I have to ask (after I thank you for joining the discussion and warn you that I want to pick your brain A LOT):

Does anybody do this kind of historical study anymore?

http://jtw.sagepub.com/content/13/2/155.full.pdf+html

Summary: it’s a 1983 annotated bibliography of the history of techcomm. I’d quote the abstract, but I don’t want to scare away other contributors to this topic :wink:


#12

Another “new tech writer” reporting in. I agree with @joaofn’s points on speed, measurement, and delivering highest-value work per unit of effort trumping other concerns. I don’t have anything to add to his well-made description of the values underlying that point of view.

Regarding dev skills for tech writers, I agree with @mikejang that having some programming or “scripting” skill is important if you are writing docs intended for engineers. For developer docs, dogfooding will often involve setting up a (minimal, toy) version of a system, whether it’s a REST API, mobile SDK, whatever. It’s not required to have dev skills for most of this, but it’s very helpful since it lets you get further, faster, on your own before you need help from colleagues.

Not to mention that learning a bit of light programming can be extremely empowering for tech writers! If you work through a book like Automate the Boring Stuff with Python, you will have enough skills to write your own code. You will also have gained at least a minimal perspective on engineering work which will make you better at writing dev docs and better prepared to collaborate with engineering colleagues (because you will probably be able to ask better questions).

Re: having more opportunity in a development role, I don’t think that is necessarily the case. I am a decent “scripter” but don’t have the CS background to work as an engineer at the company I work for. Rather than struggle to be an average programmer, I prefer to focus on being a good tech writer who has higher than average technical skills (maybe) for my role.

As Scott Adams (the Dilbert guy) says in Career Advice: rather than trying to be the best at one thing, you should try to be in the top 25% at two or more things.


#13

Hi all,

I’d like to point out, however, that the documentation that is most often discussed within Agile is not the documentation that is delivered to the customer. It is the internal documentation by which a product is created. And that is specifications or UI designs or whatever. So while it’s important to value some documentation to none, it’s not the documentation that your user ever sees (unless you are doing developer SDKs and the like and are eating your own dog food). Does that make sense?

(I’ve a long time tech writer, who’s done both old and new school. Just FYI. It’s fun sitting on that pointy spikey fence! Not! Ouch! :slight_smile: )


#14

FWIW, I think many of us write in the world of DevOps,

where the “end-user” is a developer / sysadmin who needs to do heavy-duty configuration – and that DevOps user ignores docs that look like they’re made for beginners…


#15

I’m not quite sure I like the traditional vs new dichotomy. I guess i can imagine more of a corporate (used a little derogatorily) vs the web/cloud/post-boom culture split, of which social media reflects so brightly. Let’s not forgot that there’s a lot of corporate work out there. And honestly, if you work in this sphere you’re going to be paid well and you’ll get a stable (FWIW) job. Second, I think the longer you’re in the TC industry, the more you turn toward working with more structured, repeatable, and scalable processes. Being rigid wrt process definitely feels more corporate, but that’s usually a choice - any senior executive would probably support a pro-customer move that may require an unexpected maneuver.


#16

I think maybe we should define traditional versus new more finely? I realize while typing and deleting that I don’t really know which one I am. Is making help systems totally old-school? Or having style guides? Or caring about style guides? Are you not new-school unless you can write your own scripts, or do you just have to not use Robo-Help anymore?

I mean, I write docs in XML and troubleshoot the build files, so I think of myself as all cutting edge [insert ironic emoji], but we still create Help systems and PDFs. We’re style guide slackers though.


#17

As I’m sure many people have noticed, there are at least two groups of documentarians here: those who create docs mainly for developers and internal customers, and those who write mostly for end users. Write the Docs is the first place I’ve encountered more of the first group than the second (and it’s great)! The challenges faced by each group can differ, though, in ways that each group can learn from. And I see some conflation of new tech writing with the first group and of (so-called) traditional tech writing with the second group. Part of this, I suspect, is because user-focused writers are not usually well-integrated into engineering processes. Often their departments were established before leadership realized the value of this. Hey, it’s not their fault! :slight_smile:

I love the forward-thinking perspective that @joaofn and @rmloveland and other new-docs evangelists provide. Change is the only constant, and in an era when every year brings us something that would have been magic the year before, we can’t rely on traditional processes to keep up. Let’s not make the mistake of assigning every frustrating process to the traditional tech writing bucket, though, when often as not the problem is the result of institutional cruft, of the natural tendency of organizations to become less flexible as they age and grow.

My point is that if I were writing for a DevOps user as @mikejang explains, my process would be entirely different from my process were I writing for minimally tech-savvy end-user customers–and so certain of my professional values would be. For example, an internal DevOps reader is not affected at all by typos (much less grammatical flubs) in body text, as long as the code samples are flawless. A paying customer, especially one with a humanities mindset instead of an engineering orientation, is more likely to judge the quality of the product by the perceived professionalism of the text. When the audience is different, so must be the process and the values that guide it.


#18

Thank you @johntheeditor! You have beautifully articulated my feelings on this subject! (To the point where I actually semi-shouted ‘Yes!’ out loud, in an empty room as I was reading your post.)

I think you’ve also hit the nail on the head of why participating in the Write The Docs community has been so powerful for so many of us. As a direct result of interacting with this group, I’ve been working very deliberately to incorporate tactics from both schools of tech writing into my own processes. I think so much of our success as documentarians relies on finding a way to write with precision, consistency, and structure, without sacrificing speed, responsiveness, and (above all) usefulness.

As @lemay suggested, the more we all interact with and learn from each other the more our craft will imrpove. Let’s all be (those vital, cross-pollinating) bees! :slight_smile:


#19

WOW! So many good arguments here.
It’s amazing to see how civilized this community is. If this were anywhere else on the web, I bet this discussion would certainly contain a few insults *high-fives everyone for being so awsome!*

I agree with @OBrienEditorial, I prefer hanging out on communities that are diverse (such as this one). You learn the most from people that don’t share your opinions.

I also agree with @johntheeditor. Your values will depend a lot on your target audience, and your processes will tend to be slower and more rigid as you grow.
Huge corporations have rigid processes for a reason. Usually the reason is achieving global scale.

Let me share a bit more of my own experience.
Me and my team work inside the engineering department, and create customer-facing documentation and training. The amount of internal documentation we produce is very limited.
I agree with @Sue. We are in the engineering department, because our product is a development platform, so even though our audience is external, they are developers, DBAs, and operations.

But here’s an interesting thing. The ultimate goal for our team is to “make our users proficient in 0 seconds”. So if we don’t have time for a feature, we prefer to use the few time we have helping the engineering team making a more usable product, than creating long docs.

Some teams that don’t interact with us so often, have an hard time understanding where we spend most of our time. This is the case of the support team.
So we need to do some browbags and share with them and other teams what we’re doing. Otherwise they see us as a documentation team that produces almost no documentation (so they feeling they get is that we’re not very good at our jobs :smile: )

The only point I disagree with @johntheeditor is that if you’re writing for DevOps, your users still get affected by typos. Lack of quality is not acceptable.
I’d argue the difference is that usually developers are hackers by nature, so even if they don’t understand the docs, they’ll try to find what they want by trial and error.

I also don’t want to blame tradicional tech writing for every frustrating, cumbersome, and slow process. I just want to raise awareness for some practices that might not be healthy for your users and for you (independently of where you stand on this old-school/new-school thing).
I want to raise awareness for the fact that rotten docs can sometimes be worse than no docs at all. And rotten docs usually appear because we decided to document everything to exhaustion, never thinking that two years from now, we’ll probably have the same (or fewer) resources to continue documenting new features, and maintaining old ones.

This topic is very important to me, because I’ve inherited lots of docs that my users tell me they don’t use. And after surveying they, I understood that it’s mostly due to bad experiences they had in the past, like:

  • Documentation that was technically wrong;
  • Outdated documentation;
  • Documentation that was written but no one could find
  • Documentation so cumbersome to use, that it was faster to experiment, and learn by trial and error.

I feel that attention to detail, style guides, good content organization are of paramount importance. But sometimes, we need to think strategically and think about why we have them in the first place.
And if we find that they are shackling us, and stopping us from delivering value to our customers, then we need to rethink them.

Finally, @Marya I wouldn’t stress too much about defining old-school/new-school. We need to deliver value to our end-users. As long as you do that, who cares about how you’re doing it? :smile:


#20

I don’t know. I’ve seen these occasionally and, when they are on a topic I’m working on, appreciate them greatly.

I get the impression, however, that these days, the preferred method is to use http://scholar.google.com or something similar. My research method was to use Google scholar to find some interesting papers, read their lit reviews and bibliographies and then follow the rabbit trail where it took me. With access to every published article in the last 20 years, it’s easy to collect a lot of references quickly. Where it gets challenging (and comparatively tedious) is when you run into older references that haven’t been scanned and put online. Then summaries such as that one are appreciated!