Traditional v. New Tech Writing, v2


I dislike silos.

I was just reading Tom Johnson’s post on “Should technical writers care about more than documentation?” I thought about the perspectives that @bradamante and @lemay shared in this topic: “Traditional Tech Writing, New Tech Writing”

As the only writer in my office, I feel sort of like an “embed”. All of our other writers are either embedded or remote.

When I started working at my current job (TW for ForgeRock), our site boss (dev) told me that I needed to work with our products as if I were QA. I’ve spent some time configuring and administering our office server lab. I like to take our products from a customer point of view, deploying as if I were in a simulated production environment. I do my best to create docs that help newer developers (and community members) understand how our products function, “under the hood”. To that end, I created my own scripts (well, I modified some existing work) to set up a recent Getting Started Guide.

Some of you know that I run the WTD PDX Meetup Group. I encourage developers and QA to attend. We’ve had startup founders in attendance as well – we’re all interested in excellent documentation.

Yes, all of these tasks takes time from my work as a writer. But I believe it makes me a better writer.


Wow, Mike. Are you STILL trying to set me up for my Prague talk?

Another way to look at the issue has also come up at Write The Docs (conferences and meetups). Are docs part of the product? Or are they product unto themselves?

Tom’s post seems to assume the latter, Mike’s post here the former. And I have always worked with the former, on teams large and small, on code projects and on GUI-driven projects. It’s my sense (based thus far on anecdotal evidence only) that historically technical writing in general, and software documentation in particular, has also tended toward the former. In fact, I’m starting to think that the notion of doc as separate product had a relatively short life, starting in the 90s or possibly late 80s, and hanging on nowadays only by thin threads.

But as I say, it’s anecdotal evidence only at the moment. Working on it, though!


I think we have to consider a third alternative, which is that increasingly docs are neither part of the product, not a product in themselves, but a product of a community. If there is an old tech writing and a new tech writing, my definition of the former would be that the vendor wrote the docs and of the latter that the community wrote the docs and the vendor was one of the contributors to that community.

The old tech writing was the docs were closed and shipped with the product. The new tech writing is that documenting the product and its applications is a shared ongoing activity the spans the lifetime of the product.

The question technical writers should be asking themselves is, am I contributing effectively to the documentation that the community is creating through all the Web content it generates on the product and the task that people are attempting with the product. Is our biggest challenge to get better at in-the-box documentation, or at community engagement and contribution?

In-the-box documentation is certainly important, because it is often the only docs available in the early days of a product. But should we regard it as the final word, or as a seed pearl around which the community content we develop, and around which we will continue to add additional value over the lifetime of the product?



Semi-related here, there’s a whole article (“Complexities in Hybridization…”) in the latest Technical Communication Journal dedicated to the identity question for technical writers.

The researcher interviews tech comm managers at a number of well-known companies and finds that the core identity of tech writers is that they are generalists rather than specialists. They have knowledge (but maybe not a ton of expertise) in information design, user experience, information architecture, the subject domain, and more. This hybrid nature of technical writer identities defines us and shapes how we interact with project teams.

In this case, you’re testing the documentation as a user would. You’re probably not doing load balancing and regression testing, but you’re testing nonetheless. This activity makes you a valuable contributor to the product that goes beyond just writing documentation.


Hi Mark,

I appreciate your point – and my guess: you’re thinking in terms of docs in open source products, where community contributions make all the difference throughout the product, in dev, in QA, in support, and in docs. IMO, Mozilla is one prime example of your “third way”.

I think community contributions can make a difference in what we refer to as “old” and “new”. But based on our definitions, I think it is easier to integrate community contributions in the “new” way, given its lack of silos.



Historically, of course, there have always been community contributions to software documentation, where “documentation” is defined very loosely. And yeah, Mike, I was thinking along the same lines as you, that “community management” is pretty much an open source notion.

That said, plenty of closed-source vendors (of software, with closed silo’d doc production) provide proprietary forums for their customers, and plenty of doc material (defined broadly) is available there. The minute a designated proprietary doc team gets involved in such forums, though, I call bad faith (and yes, I’ve seen it happen).

Community forums can be excellent places for dedicated doc teams – working on open-source or proprietary projects – to get good customer feedback and plan for doc improvements. But there are so many variables, so many different possible sets of relationships between dedicated doc teams and customers who provide doc content, and between kinds of content, that I’m inclined to see community-based “doc” production as orthogonal to the doc-as-product/doc-part-of-product comparison, not as some kind of third way. (The product or project itself is, of course, one crucial such variable.)


Hi Mike,

Actually, no, I mean any product that users share information about on the Web, which certainly includes open source products, but a great many more besides. When I say that the community contributes to the documentation, I don’t mean that they contribute to the developer’s docs repository. I mean that they put the content on the Web, where search and social curation can find it and incorporate it into the corpus of information on the product and its uses.

It is very common today for people to Google for help with a product rather than going to the official documentation. If the official docs are not where Google can see them, then they may not form part of the “documentation” that the user sees at all.

In his book, Everything is Miscellaneous, David Weinberger makes the point that the organization of content is now something done by readers rather than writers. The Web creates what I have called “dynamic semantic clusters” of content – content on the same subject from different sources. The “documentation” for a given issue with a given product is today the dynamic semantic cluster that the Web assembles when the user makes their query.

Technical writers can contribute to these dynamic semantic clusters by producing individual pages of content that are not sequentially or hierarchically dependent on a larger documentation set. I call this the Every Page is Page One approach.

Now it is interesting to speculate how this thought intersects with Laura’s new tech writing – tech writing that is more closely attached to the development organization. It may make sense that the two are connected – that a more open-ended style of ongoing contribution to the Web’s total knowledge base on your product, rather than a close-ended publishing of a manual, meshes well with a more embedded style of tech comm organization.


True, there has always been community documentation. The difference today is that the Web and Google effectively make all the extant information on a product a single source that the user can query from a single point, and hyperlinking and social sharing mean that people can stitch together material from different sources.

In the past, there were multiple sources, but you had to consult each source separately. You had to find and identify each source separately and search it separately. The individual identity and the individual architectures and navigation of each source was therefore primary.

But today the Web is making it all one. Dynamic semantic clustering means that when you ask a question about a problem with a product or technology, you can get ten pages on the same subject from ten different sites. That is the documentation as you experience it. This is, to be sure, a very loose definition of “documentation” in the traditional sense. But that looseness is very much the point: the documentation that people actually consult is not the tightly bound manual of old, but the very loosely bound – semantically clustered – collection of relevant content provided by the Web.

That is the game changer: not how documentation production is organized or where it is sourced, but how it is found and consumed. It makes the person with the best answer to an individual question or problem the primary documentation resource on that issue, regardless of their role or location.


Hi Mark,

I’m going to suggest that we split this thread.

The topic that you bring up, related to how docs are organized, is different from the topic at hand, the job functions for tech writers yesterday and today.



Hi Mike,

I agree that how docs are organized and accessed is a separate topic. But I brought it up because I believe it changes the job function of tech writers yesterday and today. If users are creating and sharing information on how to use a product, and if readers are creating dynamic semantic clusters of information from multiple sources, that changes the role of the “designated” tech writer.

In organizations that don’t acknowledge the change, or are not affected by it, life for the tech writer may go on as always. For other organizations, it is clearly changing the tech writer’s role, both because the content organization and publishing component of the traditional tech writing role changes (updating a wiki does not require the same skill set as publishing a book), and because the kind of material that the organization needs the “designated” tech writer to produce, and the time frame in which they need them to produce it, are different.

So, very happy to split off a thread on how the Web has changed how people access, organize, use, and contribute to technical communication, but the above is the point I wanted to make in this thread.



Hi Mark,

I do not agree with either of your assertions, but I will set that aside, and focus, in this message, on the way we’re discussing this topic.

I therefore suggest that we split this into three separate topics.

  1. The original discussion of “new” v “old”, aka, silos v. embeds
  2. The way docs are organized, based on “new” ways of accessing information
  3. The effect of new ways of accessing information on the job function of the documentation developer.



Something about “silos v. embeds” shifted my perspective a bit, even though that’s part of what you originally posted, Mike, and I thought I’d share this.

In my experience, it is possible to do both. I’ve worked for the past eight years in a traditionally silo’d group, but for a few years the members of my team and I were also embedded on product teams. It wasn’t ideal – our tools, process, publishing workflow were still silo’d, so reviews were tricky to manage – but overall it was definitely my best experience at this company. It worked well for writers and the rest of the product team, and helped produce better product and doc. It also tended to produce doc that was more tightly integrated into the (rest of the) product, because writers as informal QA often caught issues – the standard old “if it’s hard to doc, maybe the problem isn’t with the doc” situation.

Sadly, it didn’t last. We went “agile.” <saves_rant_for_later> (Note that I’m not dissing on agile per se, but agile in a corporate environment is often laughably what I’ve learned to call waterscrumfall. Yeah, that thing.) Docs and any consideration of text anywhere in the product were sidelined, not by explicit decision but by (fairly standard) failure to pay attention.

Now, ironically, in this sidelined-writers model, I’m trying to help produce text that is integrated across the entire customer experience (full-stack writing, I’ve seen it called): UI labels, instructional text in the UI, Help snippets in the UI, tooltip Help, and a (mostly context-sensitive) full-on “Help system.” (And eventually docs for APIs that will expose some of this functionality.)

It’s quite a lot harder than it should be, although not just because of the silos. But the silos really get in the way. The real irony is, we’ve been able in the past to transcend the silos. But now they’re back, and getting in the way of what is supposed to be a more integrated approach to the product.

This isn’t quite about “new” v. “old,” but FWIW, the larger sidelined-writers approach seems to feel to my (doc) team like a giant step backward. We all worked better – individually, and as a team – when we were more embedded.

And I guess I’m also trying to complicate the discussion a bit, to suggest that new vs old, silos vs embedded, are useful categories for discussion, but that when we look at real-world scenarios, things often get mixed up, other variables introduced, and individual stories don’t fit so neatly into the containers we want to define for them. (At the same time, though, that’s why we have these discussions, to try to make some sense of the messier reality we deal with on a (near-)daily basis.)


I think this gets to the heart of the integrated vs isolated issue, which is one you see across businesses and across systems. The problem with integration is, what happens when one of the integrated systems is disrupted – such as when development decides to go agile.

The more closely integrated a system is, the more a disruption of any part of it disrupts the whole. When dealing with the disruption, it is easier to isolates the parts and work out the disruption in the individual parts. Reworking the whole integrated system might be a more ideal approach, but it is simply too hard. You need to isolate the systems to fix the problems.

And then you integrate again, only to have another part of the system disrupted, which again forces you either to fix the entire integrated system or to isolate the parts and fix them separately.

Leaving the functions isolated then starts to look like a good idea, since it means that my function is not always having its world turned upside down by disruptions to someone else’s process. But isolated processes have trouble with coordination and communication and eventually it starts to seem like a better idea to integrate. And then the cycle continues.

On the systems side, it seems to be generally conceded that loose coupling is the optimal strategy. Achieving loose coupling between business functions, however, is not so easy – or at least so well understood.



Congratulations on transcending the silos – when you can :smile:

Even as an “embed” tech writer, I have to have the courage to push, to ask, to take the risk of “looking stoopid”. I’m currently working on UI text.

This work is beyond my job description – but I feel fortunate, as I have the support of my doc boss and product PM, because we know it will improve our product.

To that end, I am using lessons from the 2015 WTD conference, in the text I propose, in the user stories I identify and create, and in the (very few) screenshots that I add to our docs. Since the conference, I’ve told the team that’s what I was going to do, and I feel like I’m making it happen! I’m not getting everything I want, but I know that every change is improving our product.

And when I don’t get what I want, I think – heck, that’s OK, because I don’t feel quite sure about what I’m doing :slight_smile: (My team knows that too.)

So to me, the “New” Tech Writing works.


Sort of as a follow-up / counterpoint

One of the difficulties with a smaller team is the lack of opportunities for mentoring. If you’re the only writer in your company, who can you learn from? But as @joaofn suggests:

I’d love to hear a defense of “traditional” tech writing. Despite Joao’s approach, I can believe that a “traditional” tech writing culture is better for writers who are newer to the profession, or perhaps “fresh” out of school.


Well … I started out with what I would now call “traditional” tech writing (although I’m starting to revise my personal definition of the term … but more about that separately). RoboHelp (HAT), MSTP, reporting into a Marketing department (not part of product team at all). And I was the sole writer.

But I found plenty of resources online, even though I’ve never joined the STC. Back then (2002), I found Techwr-l very useful (and probably “traditional,” although I haven’t gone back to their archives to verify). And I worked pretty closely with support and QA from fairly early on, also eventually sales and dev. (It was a small company overall.)

But I’m wanting more and more to interrogate these terms more closely. They are useful as abstract categories, but the more I ponder individual stories and scenarios, the more I see them breaking down. Or, to return to the metaphor of @lemay’s original post, in need of more cross-pollination.


I also didn’t see @lemay’s original tweets as “traditional” VS “new” but more as efforts to understand the differences, point out the contrasts, specify elements of each, and suggest that the new has perhaps more to learn from the traditional than it has yet quite acknowledged.

But yeah, that would be the manifesto for my Prague talk, so I’ll stop now :slight_smile: