The death of technical writing, part 1

For a few years now, I’ve been worrying about the future of technical communication as a career. Not that user docs will disappear (as much as most people might want that), but techcomm as a unique job title, as opposed to one of many tasks that someone might have. I remember hearing Noz Urbina telling us that we were doomed, back at Lavacon 2012. And I attended a few webinars at that time that were also very negative about future prospects.

They’re right: We’re doomed. Pack up your pens and find another use for that English degree.

I’m exaggerating. Right?

Technical writing/tech communication is going to be around for a while. But I think it’s going to be more common to see that job title in legacy industries. You know, those places where writers still write *manuals*.

So industries where there’s lots of rules and regulations and everything must be thoroughly documented. Those rules change slowly, after all. And larger software companies that have huge, complex products (databases, for example), which are going to stick around for a few more years, at least.

At least in some form, and for an increasingly limited number of pure technical writers. To be honest, I’m seeing more job postings than now, mainly for senior technical writers. So there’s still jobs to be had.

But apps really scared us, right?

Apps are the worst, right?

Apps are utterly horrible things that don’t require documentation. Or at least not nearly enough documentation to justify a full-time writer. Apps provide a simple, targeted workflow (ideally), with streamlined UI that doesn’t need a lot of explanation.

Which also means that you’re not going to do full database administration or build a billing system on your phone, but more people using apps instead of desktop software means fewer people reading manuals.

And I think we’re the only ones who worry about that. Unless we’re the ones using the apps, and then we admit to a small amount of pleasure that we won’t have to read yet another poorly-constructed manual.

But apps aren’t replacing enterprise software. At least not entirely. Not yet.

But I still think we need to adapt to a changing world.

What have we done to deserve this?

We’ve walled ourselves off, building a fortress of complex tools that no other teams can penetrate. At the same time, we’ve seen successive waves of programming languages, each one easier to use than the last. What are we seeing? Simplification. Ease of use. A learning curve that gets less steep every time. Languages that drop features that aren’t used, or aren’t used often.

And what has techcomm poured resources into? DITA. An arcane, overly complex language with a massive learning curve that requires specialized tools.

Why are we doing this? Because we’ve been trying to cram every possible feature into it that will allow tech writers to rewrite those massive manuals that we’ve been writing for years.

We’re retaining complexity when we need to reduce it. We’re holding on to features that don’t make sense in a modern, mobile world.

What are our coworkers going with? Wikis. WordPress. WYSIWYG editors and tablet apps.

Throw it away

When I switched from Structured Framemaker to a wiki, I was shocked by how much I couldn’t do. I lost an enormous amount of control over the structure of my documentation, from the overall layout to smaller things, like picture captions (I tried; they never worked well).

And then I learned what I could do, encapsulated starting with a single reference topic. The basic syntax was…well, basic.

But it worked. And here’s the thing: My audience didn’t complain. Our customers (yes: customers) aren’t looking for the perfectly-styled documentation that follows strict rules that make sense to us and no one else.

Where’s our drag-and-drop documentation?

I need content reuse; I don’t need to write a manual. My customers don’t want manuals, they just want to know how to use the features in the product that they purchased (or that their bosses purchased and they have to learn to use).

Basically: What does this thing do? Ok, then how do I make it do that? And what else can it do that I haven’t even thought of?

I know DITA makes sense for many, many writers. You want to be able to reuse each and every piece, and enforce a very strict style? Yeah, DITA’s where it’s at. I just think it’s packed full of too many things.

I want drag-and-drop documentation. I don’t want arcane tags and references and IDs. Yes, I know how powerful those are; but so are pointers in C++, and those are a notorious source of frustration.

I want a clean, straightforward, easy to use documentation tool that, most importantly, won’t get in the way of the writing that I have to do. I don’t want think about every tag for every sentence. I just want to research, write, and publish as quickly as possible.

The treadmill is speeding up

Unlike the old days of writing manuals where projects were measured in months, even years, today my projects are measured in hours.

In the last week, I:

  • Launched a massively updated knowledge center, with the help of contractors who designed and coded the CSS. It’s a really nice site, and I’m sorry it’s behind a login.
  • As part of that, I needed to copy a lot of content, reorganize content, and fix every link in the docs.
  • I needed to copy content to support a second product, and rewrite many topics to change the product name and small differences in functionality.
  • I needed to write new documentation for that product (although that was just two new articles).
  • I had to build a structure for project documentation on our internal site.
  • And I had to answer support tickets.

“Become a DITA expert” does not fit into that schedule.

But it’s bigger than DITA

Yes, I’m ranting about how DITA isn’t absolutely perfect. Again. DITA won’t save technical writing, but it also isn’t killing it.

“Unnecessary complexity” is only one thing that’s hurting our profession. The real problem is this: What does a technical writer do for the business? What business problems do they solve?

We’ve been told, and have unfortunately accepted, that user documentation is a “necessary evil” that businesses must deal with. But that’s a stupid, self-defeating reason, and the obvious next question is: Fine, but what else do you bring to the company?

Being able to write good product documentation isn’t enough. Being a DITA expert isn’t enough (or not enough for more than a handful of people).

In the next post, I’ll tell you about what I see as some solutions to this problem.

65 thoughts on “The death of technical writing, part 1

  1. Bravo, Neal. Well said.

    Indeed, we need to be radically simpler: simpler in what we deliver, simpler in how we deliver it. Simpler, more social, more immediate, more responsive, more integrated, and more engaged.

    Does that mean we give up on structured writing? No. Structure done properly simplifies processes, increases immediacy, and improves quality. But we need to reset and rethink. We need a structured writing approach that is designed for the social, the immediate, the integrated, and the online, rather than one aimed at traditional forms of publishing.

    • Thanks! I agree with those goals: The benefits of structured writing are huge, and I don’t want to throw that away. We need quality, consistency, but with documentation that appeals to the reader (more informal? embedded?), and doesn’t require a complex publishing process.

  2. Very interesting post! I totally agree with you that tech writing as we know it will no longer exist at some point. But, to me, this is a wonderful and exciting thing. We are moving away from creating static PDF files that no one ever read anyway and starting to produce information that is actually useful to our customers. Yes, it will require more from us than having an English degree. We need to be technical, interact with our customers, become their advocates, think outside the box. But isn’t this great?

    I’m looking forward to your next post in this thread!

    • Yes, it’s very exciting. That’s why I love what I do, and why I want to keep learning and expanding my skillset. We need to break out of the old process of sitting in our cubes, writing long manuals, publishing PDFs, and then doing it all over again. And again.

      Without taking the time to understand our customers and delivering content in ways that they really find useful and engaging.

  3. I moved our documentation to a wiki eight years ago. We clone a subset of it to an external wiki where it is available to customers. This year – going for simplicity – I stopped creating a RoboHelp application and instead we now point the links to the external wiki. We built an in-house application to document the public parts of the source code and that goes to wiki. Meantime, I have been instructing and coaching our software engineers to produce technical documentation themselves (been killing some golden geese by telling them that grammar and spelling are not important as long as they make it complete, correct and understandable).

    The next step is a usb-based wiki clone where the software itself will create stub wiki topics so that the key users can create their own personalized documentation.

    So, in some ways I would endorse what you say (I am the only technical writer in a company of nearly 500 people) but in other ways I would say that I have simply moved up the food chain (OK, yes, I do GUI design, usability, I look after open source software licensing, localization, and I run the wiki engines too, so my life hasn’t really got much simpler and I do wear a lot of hats … but I still create an in-house magazine using FrameMaker every three months).

    • My argument is that “technical writing” is dying because we’re no longer able to be writers and nothing else. As you say, you’ve “moved up the food chain,” but in doing so I’m sure you’ve expanded your role far beyond the original concept.

      What you’ve done sounds amazing. For example, that sort of collaboration with your engineering team is exactly what we need to pursue, and I know that it’s not easy to pull off. Congrats!

  4. Some interesting points in here, but an unfortunate conflation of “DITA” with “the old way of doing things” along with the idea that obsession over formatting is bad (totally agree) and that’s somehow related to DITA (not so. Most of the anti-DITA pushback we get is related to formatting issues.)

    The programming analogy is interesting, but in addition to the simple scripting languages that get all the publicity, there is a robust market for Java developers, embedded systems developers, and so on.

    Here’s the key statement from your article: “The real problem is this: What does a technical writer do for the business? What business problems do they solve?”

    If you start with the business question, you can work your way over to the right workflow. In some organizations, that’s a wiki. In others, it’s DITA. Don’t conflate your very strong argument that change in tech comm is needed with the idea that the workflow that’s appropriate for your organization is The Universal Answer.

    • Thanks for your comment. I agree that I let my anti-DITA bias get the best of me, and I wandered off topic. My argument against DITA isn’t formatting, exactly, but that it enforces a far too rigid structure on the documentation. This doesn’t allow for the quick, casual documentation that I’m asked to create (but as you said, this is *my* process, and certainly won’t work for everyone).

      But how would DITA work with Simon’s process? He’s getting content from engineers, and I don’t see how that would fit into a DITA process without a lot of work. Then again, that doesn’t fit into many doc processes, DITA or not. Could the answer be “DITA for the doc team, and no one else”? (I suspect that I’ve missed a lot of techcomm blog posts that explain that.)

      • It sounds to me as though Simon’s process is working just fine, so I can’t think of a reason to shoehorn DITA (or anything else) in there. :-)

        That said, let’s assume there’s a requirement for “contributions from engineers” AND for the localization/structure/etc you get from DITA. In that case, I would look at a lightweight XML editor for the engineers and a full-blown system for the tech writer/publisher types. Software engineers are often perfectly content to write XML in their favorite programming editor/IDE.

      • Good point about engineers being good with using XML editors. Have you done that before? Do you anticipate, or have you seen, any problems integrating that into an existing workflow?

        I know that at some point, I will need to adopt a better documentation process. It might even be DITA, or something similar. But as Mark said, I think that the available tools require significant compromises, and I’m trying to put that off as long as possible.

      • This has always been a problem with structured writing systems — and, indeed, with tech writing systems generally. The range of things we create goes from the highly structured to the highly ad hoc, and from the perennial to the ephemeral.

        In the book based world, this presented the problem that the same tools that were best for the structured and perennial were very different from the best tools for the ad hoc and ephemeral (not to mention the other possible permutations), but at least the reader accepted it when you delivered these various things in different pieces with little or no connections between them.

        In the online world, the difference in optimal tools for the various permutations is the same, but we add the reader’s expectation that they should all be current and integrated.

        Thus choosing the ideal tool for an integrated technical communication system is difficult. Whatever tool you choose is likely to suck for some part of what you do. Making a final choice is often about deciding where you need to perform best and where you can afford to take the hit.

        Our current tools all have their sweet spots and the weak spots across this range of requirements. We need to keep working to develop something that is more balanced in its capabilities across the range. Letting go of some of the more high-end paper-world publishing requirement will certainly be a necessary part of that development. Wiki’s and DITA both represent steps on this road, but the journey is far from finished.

      • I agree with Sarah here. (But I must say that I am very biased since I work for a company that provides a DITA CMS :). Engineers can use XML editors (and are more interested in using them than, say, using Word to provide content). In my company, engineers use oXygen to provide contents in DITA and write their specs, so I can easily reuse their content. But we are recognizing that there is a need for a product that provides a light interface to DITA for casual content contributors and reviewers, so this is something that we’ve added in our offering.

        But I don’t want to turn this into a DITA vs. non-DITA discussion (even if I’m a DITA enthusiast) because I think you bring up very important points in your post that we need to address as tech writers, no matter the tools used.

  5. I guess those few of us old timers who started out in the marketing world have always thought this “writing only”approach was doomed. My job hasn’t been labeled “technical writer” since 2001. But I have been writing, designing, analyzing, producing and publishing “technical” content in a variety of forms for internal and external audiences for many years.

    We cover a lot of DITA on TechWhirl, but in my consulting/contractor world, my clients have no idea what it is much less why they should consider it. They want content that answers the real questions that customers have. They also want better processes for customer support, better and faster time to market, and ways to cross-sell and upsell services and products. It calls for a whole range of tools, in which you need to be conversant, but not necessarily expert. Where many technical writers/communicators fail is in not recognizing the consultative, analytical, and persuasive skills necessary to do what the organization needs for its content… Trying to sell DITA solutions for DITA’s sake, or the value of technical writing to an organization is a losing proposition. Describe your value in terms that your clients use. Be a consultant who focuses on content and communication to solve business or organizational problems…then you can pretty much bypass the doomsday predictions.

  6. Dr Tony Self did a session at the UA Europe conference a couple of years ago entitled “Any colour as long as it is black.” – In it he compared Techcomm to the automobile industry in the early/mid 20th century. The arrival of Henry Ford revolutionalised car building to the point where others had to evolve or (largely) die out. I added “largely” in brackets because even now there are highly specialised car and car part manufacturers that bucked the trend. They are successful but occupy niche areas. Tony’s thesis was that we will go the same way if we do not evolve.

    • Thanks for the link. Based on many of the comments, I think the clear advice is “Structure your damn docs, already!” Although I’m still leery of the costs, it’s also true that no one wants hand-carved buggy whips anymore.

      And it still feels like that’s one part of the answer, where structure and automation will definitely help, but documentation can’t be all that we do.

  7. [1] If the point is not to be ready to use different technologies to do your job, then that’s true for almost everything.

    [2] You spend a lot of time criticizing DITA. I don’t know it (I haven’t actually started working as a tech writer), but it seems that one spends a lot of time at the beginning so that it’s easier to change later, and/or to generate versions of the documentation in different formats. That can still be a valid trade-off, no? That’s one of the things they’re teaching in my tech writing course.

    [3] Users still need help documentation of some sort, and there will still be work for people who know how to write it well, no? Not all subject matter experts can do that.

    • 1) It’s not just technologies, it’s “tasks outside of traditional technical writing.” And it’s true that we’ve been arguing about the limitations of “technical writer” as a name for a while now. But we haven’t quite solved that issue.
      2) I don’t disagree. I just think we need to be honest about the limitations of DITA, and what it means for collaboration with other teams. Mark Baker’s comment’s are good explanations of this. The other issue is that “spending a lot of time at the beginning” is a luxury that we aren’t always given. If the company uses Agile development, dev cycles are very short. But as you say, then you lose the features that you get with properly structured documentation.
      3) I certainly hope so! It’s very interesting to me to see at what point in their development a company realizes it’s time to hire someone to create the documentation/tutorials/instructional videos. It’s usually when “the stuff the SMEs create is good enough” is no longer good enough, but I haven’t seen a lot of consistency about that.

  8. You are completely off the mark when it comes to the meaning of structured authoring in general, and DITA in particular, for the future of technical information. Note that I am not using the term “technical documentation” anymore and this is for a reason. The trend is clearly toward technical information that can (also) be consumed by software machines.

    Pushing your content into a wiki may be easier but does nothing for intelligent software, as the contents remain completely unstructured. Unless you build a wiki based on structured authoring (preferably DITA), which defeats the purpose of your choice to go for the low-hanging fruit.

    If my content is structured, an automated process can reuse it to find those pieces that are of interest to it, while being totally agnostic about anything else. That is the main reason why XML has taken off in the software world. The reason why almost everything is now based on XML. The reason why I can now create an interactive information app by drawing a flow diagram in Visio and push a button to execute an XSLT. No writing involved other than the few instructions I have put in the bulding blocks of my flow chart.

    The beauty of DITA is that you can extend (via specialisation) or reduce (via constraints) the standard without breaking it – thereby ensuring that all the tools that know about DITA will be able to process your extended materials without crashing or producing nonsense. This is not the case in much more complex XML standards like S1000D and DocBook. If you find that DITA is too complex, get an expert in for one day to define constraints and you have made the complexity manageable. If the semantics in DITA is not helping you in your business domain, get an expert in for one week to define specialisations and you have adapted DITA to your needs.

    An increasing number of apps are information apps, built by software using XSLT and based on DITA source materials. An increasing number of web-based help systems are built by software using XSLT and based on structured content in one standard or another. Wikis are prehistoric when compared to the agility you can reach with automated processes running on structured information.

    It may be true that I need to devote more time initially to make my materials structured, but that extra effort is enormously more beneficial to the possible reuse of my content via all kinds of automated processes, pushing it out to all kinds of media in all kinds of formats. Without extra work, once it is set up.

    Yes, there is work involved in changing from the totally unstructured and chaotic world of technical authoring we are all striving to leave behind. I agree that tools are still somewhat clunky and good basic training is not available from many sources. But going for the low-hanging fruit in the form of wikis is not going to move you into the direction of structured authoring at all, and therefore it is not going to keep you fed for a long time.

    • I agree that I spent too much time attacking DITA, when that’s not my real target. I really appreciate your thoughtful response, and I really like your summary:

      Yes, there is work involved in changing from the totally unstructured and chaotic world of technical authoring we are all striving to leave behind. I agree that tools are still somewhat clunky and good basic training is not available from many sources. But going for the low-hanging fruit in the form of wikis is not going to move you into the direction of structured authoring at all, and therefore it is not going to keep you fed for a long time.

      I’d argue that the tools are more than “clunky,” but then I remember that I spent years learning Framemaker, and trying to get Word to do anything complex reveals just how clunky (and hostile) it really is.

      • Just remember the days (well, before our time), when cars could only be driven by engineers and required a man with a red flag running in front of it to warn the ‘normal’ pedestrians that something dangerous was coming. This is more or less where we are when it comes to tools for structured authoring: pioneering, trying to define completely new paradigms for the information world of tomorrow. Yes, they can be scary at times, but we have to see beyond our fears to see the new opportunities they are offering us. Technical writer is a profession of the past. Information architect is geared towards the future. This could be the same person, if s/he is willing to step out of her/his comfort zone. As a philosopher without any computer science background, I can relate to the scary bits but I can certainly vow for the incredible perspectives it has opened up for me.

  9. Pingback: The death of technical writing, part 2 | Customers and Content

  10. For some reason this has become a DITA vs. Wiki argument that somehow manages to circle around your main thesis that tech writing is a dying profession. If you are correct, I don’t think Wikis or DITA are likely to survive. I suspect the more likely outcome is that Wikis and DITA will persist (in different and complementary roles), but that the job of “Technical Writer” will change.

    The evidence I have been able to find supports this. Over the past two years the number of Tech Writer job postings in the US has dropped significantly — despite the fact that the economy has been improving. The requirements for “traditional” tech writing tools (ranging from Word to FrameMaker) has also dropped, while there is a call for other skill sets involving experience with XML, CMSes, WordPress, various programming languages and also Wikis. So the tools Tech Writers are expected to know are changing, which tells me that the role is changing as well.

    Delivery mechanisms are also changing, and you touched upon it when you talked about apps and better, more intuitive UIs. When was the last time you needed a manual to understand how to play a video game? The trends I am seeing in Augmented Reality (via Google Glass and Oculus Rift) suggest that “technical docs” for hands-free applications in this area will be immersive and more visually-oriented than text based. Not everyone is going to need hands-free tech docs, but I’d be surprised if it doesn’t have a significant impact on how we are expected to deliver content in the near future (responsive web design anyone?)

    I think you have the wrong idea about “unnecessary complexity” when it comes to understanding things like the DITA standard. The focus in our profession ought to be more about “necessary complexity”, in other words, meeting the needs of our customers wherever they are and with whatever devices they having using whatever tool (or standard) works best. So ultimately the focus ought to be less on “DITA vs. Wikis” (because both are good in their particular niche) and more being about how to deliver useful content that provides value to the company.

    I’ll be interested in seeing Part 2, but I hope it is less of a screed against structured content and focuses more on the real changes happening to the Technical Writing profession.

    P.S. I think this article ( is also relevant, and speaks to how the profession is changing/dying in a way that has nothing to do with structured vs. unstructured authoring. (Is there anyone else in the forum completely devoid of grey hair? ;-)

    • Hi Keith. Yes, I did see the other article. I had my question marks at the graph of job experience against age, as a 20-year old will obviously never have 5+ years experience. But yes, it does show that technical communicator has not (yet) been a profession in the past decades in the UK, and people tend to grow into it from other professions (for a variety of reasons). It would be interesting to have similar statistics from Germany, where ‘Technische Redakteur’ has been on the curriculum of many colleges and universities for decades. In the end, technical writer should be a dying profession in my opinion, as it should evolve towards information architect – and its financial rewards should grow with it.

      • I suspect you are right Jang! We are likely to see more Information Architects and Content Strategists who focus more on the overall needs of the users of content, and help find ways of delivering it, be it via wiki, structured content or some other wholly different medium.

    • I think that this has become a DITA vs Wiki argument for a very good reason that is entirely relevant to Neal’s point. DITA, whatever its strengths and weaknesses, is a publishing platform designed to support what we might call the conduit of authority model of communication. That is, qualified experts write, structure, and assemble discrete information products which are then published them as a unit. It represents the technical *publishing* model of tech comm, the model that Neal suggests is dying.

      Wikis, on the other hand, were designed as collaboration platforms. The wiki philosophy is that everyone is an author and everyone is an editor. Wikis may not be as operationally efficient as structured writing systems, but at their best they can achieve as much structure and integration through collaboration as structured writing systems do through metadata and algorithms. Wikipedia is a prime example of this. The wiki model represents the collegial/social model of technical communication that may represent more of the future direction of the profession.

      The contrast of tools, therefore, stands proxy for the contrast of models. This is not to say that the tools cannot be used for working in a different model from the one they were designed for. Wikis are often used in conduit of authority processes, and, as some have argued here, DITA can be used in a more collegial/social process, at least within an organization.

      I am a big believer in structured content. I am also a believer that the conduit of authority model of tech comm does not work in the age of the Web. Every Page is Page One. We are contributors to a colloquium on our product, and on our industry.

      The tools on the collegial/social side are relatively immature compared to those on the conduit of authority side, which makes it easy for DITA to win a feature-war argument with Wikis. But that is not the point. In an Every Page is Page One world, we need to develop tools optimized for this world.

      As much as I am a believer in, and lover of, structured writing, I greatly fear that by promoting it too strongly, we may be setting up a false secondary goal that distracts and delays the profession from reaching what should be its primary goal: the shift from a publishing focus to a colloquium focus, from books to Every Page is Page One.

      In the last days of sail, the clipper ships were faster than the early steam ships they competed with. But the model was wrong: the age of sail was over. Structure can be of enormous benefit in both models. But it is the choice of models that will determine the future relevance of the profession.

      Currently there are not mature tools available that combine the collegial/social model of a wiki with a structured approach to content (thought one could make an argument that StackOverflow is a big step in that direction).

      DITA and Wikis are both good choices for doing Every Page is Page One today, because they are here and they are mature and they are supported. Neither should be considered an end point, especially in a profession in such rapid evolution.

      • My main gripe is that the article doesn’t really address the thesis of its title: the technical profession *is* changing but ends up being more a screed against structured authoring. There’s an interesting idea there that I don’t see properly followed up.

        I also take your point about “conduit of authority model of communication”, but Marshall McLuhan would say that’s true of any media. Even the Wiki model reinforces majority opinion by design (ever been in an edit war on Wikipedia?) I think that argument is a canard, since highly technical information (am thinking semiconductor data books for example) needs to come from SMEs who designed a chip. It is only a “conduit of authority” if there is no way for a customer to respond to it, and tools like DITAWeb allow users to comment on documentation.

        I agree that every page should be page one, (and yes, that’s a good title for a book ;-) ) and this has long been true in user-centric design for web content. One place where wikis and structured content currently clash is in providing consistent information, something that wikis tend to be poor at and that structured content is good at. CMSes are better at both tasks, and the better ones bring them both together. Again, DITAWeb would be a good example of marrying what you would call an authority model of communication with a more collegial one.

        So I think “DITA vs. Wiki” stance is too simplistic, and divisive rather than being informative. It’s ultimately not about structured vs. unstructured content, but *effective content* that a) users can find and b) is useful to them whenever and wherever they are. What I think is more interesting is how the tech writing profession is changing in order to (finally!) adapt to customer’s real-world needs, and I don’t see that addressed here.

      • Kieth,

        While I agree that there is information that can only come from the SME, this may not be as prevalent as we might suppose. In the 90s, Peter Norton documented the Windows API better than MS did, including revealing many hidden APIs that MS would rather not have had revealed. A recent study has shown that StackOverflow documents most of the Android API in much greater depth than the official documentation. According to a story I read recently, the DropBox guys were summoned to a meeting with Apple engineers demanding to know how they got the synchronization to work in OSX. According to the story, the DropBox guys thought they were going to be sued, but it turned out the Apple engineers simply wanted to know how it was done because they could not figure out how to do it themselves.

        The point is, most of our technology is not really opaque. Someone with the right skills and motivation can figure out most things, including things the original manufacturer wished to hide, or did not know about themselves. The Web makes the findings of such people freely available to all (when they decide to share).

        The fact that the Web provides access to the information created by these spelunking engineers is a one of the many reasons why people increasingly turn to it when they want information. It is a source not colored by the commercial interests and economic limitations of the vendor.

        You are certainly correct that there is still a conduit of authority, but my point is that the vendor’s publishing system is no longer that conduit. Authority is, to a greater degree than ever before, socially mediated (as your example of Wikipedia edit wars illustrates). Authority cannot be assumed; it must be earned in the marketplace of ideas.

  11. And what has techcomm poured resources into? DITA. An arcane, overly complex language with a massive learning curve that requires specialized tools.

    Amen. I’ve been making this case for a good 10 years. In 2007, I wrote a series of articles called “The XML Heresies” about the (consultant-driven) tendency to over-complicate everything in techcomm, and why we need to focus on simpler systems that let us keep control. A consultant did write a nice little hit-piece about it, getting quotes from other consultants (including one who has posted here) but not from me. It drove lots of viewers to my blog, and amazingly no acerbic comments. I’m digging those articles up to repost on our internal blog at work.

    Extremely process-driven environments like aerospace need to have complex systems that demand rigid structure for their documentation. But most of us don’t.

  12. When I first started as a tech writer I interviewed at Dunlop to write documentation for aircraft undercarriage systems. They still had a typing pool who typed up handwritten copy from the writers, who marked up the copy with pencil and had it retyped. Camera copy in those days really was camera copy, and cut and paste really was cut and paste – blue pencil, calculator to work out scaling, calc over the top and mount the photo on card with glue.

    I ended up at Lucas Aerospace documenting jet engine control systems, and met my first word processor. It was some years, via TeX and LaTeX on a mainframe computer, before the first PC DTP packages arrived … and I had a writer on my team refuse to learn to use it because he felt it was “beneath him”.

    I loved the Internet (BiX was fun, but it was a different place in the pre-AOL days). Then Tim (a tech writer) came up with HTML, and I built my first Intranet in 1993 … and, oh, how I hated Netscape and that dreadful blink tag! SGML was a Godsend and not so many years later I was at the forefront of HyTime, Interactive Electronic Manuals and virtual realities (those years in defence and the European Space Agency introduced me to technologies that we STILL haven’t caught up with yet!). I so miss HyTime, DSSSL, and Topic Maps. It really looked like the world was going to open up to linked documentation, virtual documents, semantics webs … but we ended up with the web. Living proof that the best technological solution does not always succeed.

    I did structured Frame (I once did a parts catalog for General Motors using MIF code from a database and a browser viewer application for Apache helicopter maintenance documentation) and, yes, I did XML. Don’t believe me? … I wrote the book on XML (well, some of them. Presenting XML was the first book on XML ever published and Teach Yourself XML in 21 Days wasn’t far behind it). The last three decades of the last century were an amazing time to be a tech writer.

    Nowadays, I don’t get to do much actual writing. I don’t get to do much DTP either, come to that. And, although I still do the occasional XSLT coding, I don’t do much structured work. I don’t do much Simplified English either (so there are some small blessings).

    Looking back at all the fuss about each of these technologies, you sometimes wonder why people get so heated. DITA is excellent for what it is used for (even though I have my reservations about brain dead off-the-shelf DTDs, but I had to give up trying to explain the wonders of architectural forms many years ago); all the technologies are OK – for their sector/application. I’ve worked on electronic component datasheets where the masses of data could only be managed with DITA-like transforms. Now I’m using a wiki to document 1500+ C++ modelled classes with all their methods, functions, attributes and relations. We extract the code, convert it to XML, match that XML with the documentation in an Oracle database and produce the final XML that I convert to whatever format I need. For each of these sectors (I’ll resist the temptation to call them niches because some them are huge) there is an appropriate skill/tool/technology combination. Some might die out, but not one of them will dominate.

    The bottom line is that the industry, our profession, has changed so much over the last 40 years that it is breathtaking to look back – and sometimes intensely disappointing. People have been shouting doom and gloom all that time – or screaming about the need for “more professionalism”. Technologies have come, and they’ve gone. Our skills have changed – in many jobs back then you were an engineer first and a writer second. The profession as a whole is incredibly varied and there is room for an amazing diversity of types of writing, tools, underlying technologies, and media (when I wrote my first docs for a Palm Pilot I did dream of having something like an iPad; but it took a long time coming). I think we are very, very lucky to be employed in such a dynamic profession. Very lucky. I can see a lot of very exciting changes still in the wings and, if we don’t fence ourselves into a dead end, I don’t see it ending any time soon.

    • I so miss HyTime, DSSSL, and Topic Maps. It really looked like the world was going to open up to linked documentation, virtual documents, semantics webs … but we ended up with the web. Living proof that the best technological solution does not always succeed.

      Actually, Simon, I would suggest that what this proves is that the question is far less about the best technology and far more about the best model.

      The Web lacks top down structure. This is at the heart of many complaints about the Web. It is also what has made the Web the success it is. In David Weinberger’s words, Everything is Miscellaneous. This was not supposed to work, but it does. In fact, it works brilliantly.

      Yes, we can point to annoying things that happen on the Web that would not happen in a system that was organized top down, but top-down organization has its own problems, mostly related to its inability to scale. Beyond certain levels of size and complexity it becomes impossible to find things effectively in a system with top-down organization.

      The Web is organized bottom-up — local clusters of content linked, often ad hoc — and accessible to filtering. Where scale defeats top-down organization, it actually helps that the Web is vastly huge and that Google is vastly popular, because it provides data for the extremely sophisticated filtering provided by search engines.

      Yes, the net you dip in this water often contains as many old shoes as fish, but it make fishing trivially easy. The technology may not appear sophisticated (though the filters are actually extremely sophisticated, even if the content is not), but the model works.

      And the fact that the model works is also driving the changes in tech comm. The old model of information finding was, first find an authority, then ask your question. The new model is, first ask you question, then (if unsure) establish the authority of the answer.

      This is what I mean when I say, Every Page is Page One. The reader picks your page out of the net, along with the old boots and tin cans, and other people’s pages, and that is their page one, often the only page of your content they will consult.

      I’m all for linking and even semantic webs, but it has to start from the page. Every Page is Page One. The Web allows readers to construct semantic clusters dynamically at a moment’s notice. That is the new model, the model that works for the modern reader.

      And this is why the old writing and publishing model of technical communication, and all of the tools, processes, and job descriptions that went with it, are in jeopardy.

  13. I love the conversation here and want to participate. I used Mediawiki (a simple model for authoring) for documentation in a very community-centric model for about 2 years. Although wikis thrive in environments where collaboration is encouraged and contributing members are articulate and careful stewards of their content (a rare environment), my experience differed. The wiki devolved into a content junkyard, full of outdated content that was basically a mess.

    People would start a page that often duplicated other content, and then abandon it when they moved on to other projects. The next person would find the page and not know whether the content was current or not, and to avoid stepping on the original author’s toes, the new writer would create a new page. The people creating pages constituted an extremely small percentage of the actual users.

    Honestly, I don’t know how the Wikipedia model works so well. I can only say that it works when there are mutual interests at stake, and I suppose Wikipedia’s model hits that win-win spot.

    It seems like for the wiki model to work, you need a content steward to avoid a free-for-all content mess, but that steward role often cannot and should not exercise authoritarian control over the content. It’s somewhat of a paradox.

    For the past year, I mostly embraced simple markup using Markdown and Google docs. But when I needed to single source the material into both online content and a printed training guide, I couldn’t. I also couldn’t manage the content very well in our web CMS. So I switched to DITA. It is more complex, but it also simplifies things in some ways. There is a predictable pattern for authoring, and that predictable pattern allows you to shape content without making a lot of mental decisions about how to organize it.

    That said, creating a custom XSLT to get content into a JSON format and then building an import mechanism into Drupal is beyond my skill level and it is beyond my interest in learning as well, since my professional expertise is in the technologies I’m writing about, not the publishing technologies. It’s much more profitable to learn JavaScript and other programming languages than it is to learn DITA publishing technologies. Certainly there are jobs for publishing tools experts, but it is a smaller niche than the technical writer for software companies.

    As for the dying profession, I have shifted my career more towards developer-oriented documentation. I think the market for API tech writers is getting stronger, not weaker. The end-user documentation role is maybe diminishing, but there is also a greater need for more technical documentation.

    • You say:
      “As for the dying profession, I have shifted my career more towards developer-oriented documentation. I think the market for API tech writers is getting stronger, not weaker. The end-user documentation role is maybe diminishing, but there is also a greater need for more technical documentation.”

      I totally agree with you, Tom, and have noticed this shift in my previous jobs, working for companies that provided mobile apps. The end user documentation was minimal (often less than 5-6 pages), but the back-end software that supported these apps required a lot of documentation. And since companies now often provide open APIs to allow external developers to extend the mobile apps, there is a serious need to create solid API documentation.

  14. From Neal (way above and no more nested replies possible): “Good point about engineers being good with using XML editors. Have you done that before? Do you anticipate, or have you seen, any problems integrating that into an existing workflow?”

    It works surprisingly well. In one project a few years back, we created a DITA specialization (I know, I know…keep reading) for man pages. So, we had DITA elements with names like synopsis and all those other lovely man pages goodies. From that, we generated both actual man pages (nroff) and also PDF via FrameMaker. The solution met all of our customer’s requirements quite nicely:

    * A system usable by engineers without FrameMaker licenses
    * The ability to generate man page output
    * The ability to generate highly formatted PDF, integrated with other (unstructured) content via FrameMaker

    There are lots of other examples, but this was a case where the highly structured/locked-down content was necessary because, well, man pages are highly structured and have a limited set of tags. There weren’t a lot of other obvious solutions to the problem. (We looked at authoring in man pages and transforming nroff into FrameMaker. Ugh. We also looked at starting on the FM side. Double ugh.)

    • Thanks for that example. And I promise I’m only hardcore anti-DITA when I’m in the middle of a rant. I’m really just afraid that I’m going to have to dive back into it (I’ve had to work with really horrible DITA implementations in the past) as the best of a bunch of non-optimal solutions (see Mark’s comments about needing to get away from a publishing model).

  15. Tools like FrameMaker, Dita and RoboHelp create a walled community. If creates a development environment that only the writer can occupy. There was a time when this was very useful. Knowing these tools was your barrier of entry into the field. It “proved” that you were qualified to be a technical writer. I’ve gotten jobs in the past simply because I knew these tools.

    At my current company, I pushed us into a wiki. We use Confluence 5. It is a lightly structured environment. There is still a tree structure behind the content, which makes it easy to export to things such as web help and PDFs and to create TOCs to guide the users. The big benefit to us was that the barrier to entry was dramatically lowered. If you can use a word processor, then 90% of the tools you need are familiar and straightforward.

    Soon after implementing Confluence, we started getting requests from development teams who wanted their own spaces on the wiki. Slowly but surely, the wiki is becoming the defacto information repository for all product information, not just customer facing documentation. Everyone wants to put their information there. We are a medium-large company with several branches and multiple products. For the first time, everyone is on the same platform, working from a single source.

    There have been plenty of issues along the way, but customer satisfaction keeps rising, and I long ago stopped hearing from writers who wanted to move back to FrameMaker. We still have one team that won’t give up RoboHelp for help output, but even then Confluence is the source of record.

    As for the disappearance of writers. I would be more concerned about Agile Development than any particular tool.

    • Walled in is exactly what DITA is not. And it is not a tool, either. It is defined specifically for the purpose of interoperability between any number of XML-aware tools, even allowing each company to have their own specialised vocabulary (sets of semantic labels) without breaking down the interoperability. So DITA is really the opposite of walling in. Try interoperability with Confluence. And I mean pulling content from various sources together into a meaningful and consistent whole.

  16. I’d like to add a few of small points to this hugely important discussion. (As it happens, I have recently touched on the questions raised here on my own blog.) The first is that we should all be reassured that the job we do – making technology easier to use by providing information – remains hugely important. The problems we have are around the tools and methods we use to do that job. The second point is that when we are faced with choices about which way to go – what others have called the “DITA vs. wikis” dilemma – the deciding factors are, in my experience, more often related to business priorities and budgets than they are to any appreciation of what would best meet the interests of the information consumers. My final point is that we still need to find a description of our job that is not only broad enough to encompass all the things we do, but can also capture the imagination of our current and potential employers and clients.

    I don’t think there’s a “one-size-fits-all” solution to any of these problems.

  17. Perhaps I should have added that my employer makes planning and optimization software. We do not produce end-user documentation as such (apart from a small common user manual that I create and technical “white papers”). We train and encourage the key users of the final application to create their own documentation. The main documentation I produce is intended for the developers who use the tools we create to make those end applications. So, my role is more of a facilitator. I work in the software R&D department, alongside the software engineers, and the audience are the less-skilled application developers in the Business Units. It’s very technical documentation for very technical users, and in an Agile environment, so a background in software development is almost as essential as writing ability.

  18. Since when did the word “apps” come to mean software deployed on phones and nothing else? An application is software designed for use by an end user; the platform it’s deployed on

    And, this article starts with a statement that makes me think you had your work incorrectly defined to begin with. You shouldn’t have to shift from being “document-focused to being customer-focused”. If you weren’t customer-focused to begin with, you were doing the job wrong. Being a technical writer is about creating documentation – physical, electronic, web site, help system, or whatever – that supplies the customer’s need for information. If you are writing a manual about a software tool that is used only by engineers, those engineers are your customers. People who must use the documentation to obtain directions or reference information they need to make the documented item work properly are the customers. Their job descriptions don’t affect that fact.

    Perhaps it would be more accurate to say you’re having to shift from being hard-info-focused to being MARCOM-focused?

  19. Garen Torikian wasn’t able to give this talk today, but he’s been thinking (and acting) along similar lines: “We need to focus on building tools that provide some level of sophistication, without overwhelming the writer or placing a support burden on engineers in a company.”

    This is exactly the sort of thing I’m looking for: (unfortunately, it doesn’t exist yet)

  20. Some points I have not seen mentioned in the discussion about wikis: what message does wiki-based documentation give us about the profession of technical communicator and what does it mean for the reliability of technical documentation?

    In some domains, wikis may work. As an example, I heard that the FrameMaker ExtendScript documentation is going to move to a wiki, so that external developers can contribute and make this API documentation better. In this case I think it will work because of the common interest of script developers, who need reliable documentation and can also gain some profile by contributing and showing their expertise.

    In many industries, however, this can never be implemented. Would you use a car for which the service information relies on wikis – where anyone can post their ideas about which parts to replace your brake pads with? How can technical information be reliable if there is nobody to hold accountable when it turns out to be fatally wrong? In some industries – medical devices, heavy machinery, chemistry, transportation, aviation, to name but a few – products would not even be allowed to enter the market if the documentation was based on a wiki. In such domains, even if an authorised technical author (by definition someone working under contract of the manufacturer, even if this is only for accountability reasons) changes some warning messages, the machine, together with the updated info, will have to go through a lengthy validation process again to regain admittance to the market. In many business domains, reliability is more important than anything else. I cannot see how such reliability can be achieved when your documentation is put on a wiki and open for everyone to edit. If you add a level of moderation to your wiki that enables full quality checks before edits are released, this defeats the whole idea of putting the tech docs out on wikis in the first place.

    The succes of wikis in the consumer market does not show that wikis are going to be the future of technical documentation, or that they should be. It just shows that some companies are not doing what they should be doing (providing good technical information about their products) and the internet is already taking over their task on all kinds of forums. Providing a wiki allows these companies to pull some of the totally uncontrollable forum stuff back into their company website, which makes it look like they are doing a fine job after all.

    But the implicit message that gets me worried about all those wikis is one that I have been hearing for a long time from potential customers: “Hey, anyone can write, right?” It was the reason to let the receptionist write the manual between phone calls, and the reason to question my quite reasonable rates as being ridiculously expensive. The fact that we all learned writing in elementary school makes it hard for many people to understand that there is more to technical communication than being able to spell your name. Technical communication is a profession that requires certain skills to do a good job. If technical communicators are pushing for wikis they are basically undermining their own profession, as they are implicitly stating that anyone out there can do their job just as well. Anybody can write, right?

    In my experience, SMEs nor end users are good candidates to write good technical documentation. You may be using a wiki or a forum or web-based forms or a voice recorder or even Word to retrieve technical information from your SMEs. You may be using a wiki or a forum or feedback forms or surveys to retrieve customer feedback. You will still need to digest all that info and convert and rewrite it (and most of all, restructure it) into well-designed and well-structured, easy-to-use technical documentation. If you do not believe that this is a crucial factor in your company, you should either give up your job title or find another company or business domain to work in.

    • I didn’t intend for this to be a DITA-vs-wiki discussion, but I feel compelled to respond to this. Although I’m not using a wiki now, my argument from a few years ago still holds true (for me, at least):

      Yes, a wiki needs a curator (or multiple curators) to stamp out spam and revert bad edits. But you’re arguing that ONLY the authorized content creators should be allowed to create any content, and I think that we need to encourage community participation.

      If technical communicators are pushing for wikis they are basically undermining their own profession, as they are implicitly stating that anyone out there can do their job just as well.

      I disagree that tech writers are the guardians of sacred information that must be protected from the masses. Honestly, I’d be thrilled if my customers were asking to write documentation. We’re dealing with shrinking resources (smaller budgets, fewer writers), and most of us simply cannot document every use case. It’s not that we aren’t doing our jobs, but that it’s simply not possible if the product has any complexity.

      If you add a level of moderation to your wiki that enables full quality checks before edits are released, this defeats the whole idea of putting the tech docs out on wikis in the first place.

      I disagree: Encouraging your users to add content helps build a community, and can be a good way of generating content that won’t otherwise find a place on your schedule. And the quality check can be as simple as “make sure this doesn’t cause harm.” If the style and tone are different…well, so what? Many companies are moving away from highly formal writing because it’s stuffy and readers don’t like it.

      Would you use a car for which the service information relies on wikis – where anyone can post their ideas about which parts to replace your brake pads with?

      Sure! Remember: Google exists. Your readers know that, and they certainly use it. We can’t pretend that they are locked into our documentation and will forsake all other sources of information. So, yes, when I wanted to learn how to change the spark plugs in my car, I went to Youtube and other sites. The reader (in this case, me) does have a responsibility to evaluate the correctness of the information, but that’s something that people have become used to.

      As technical communication professionals, we can curate content created by other sources (SMEs and/or end users). Most wikis have basic tools to help you prevent (or at least revert) vandalism and block spammers. It’s not that “anyone can write” (and I’ve dealt with that mindset, too); most of our SMEs and users won’t try to write, so why turn away the ones that are engaged enough to offer to help? If nothing else, that helps us engage with our customers and increase customer loyalty, because that gives them a stake in a part of the product.

      • Of course it is good to get feedback from real customers of your products. I have spent much time on community forums finding answers to questions that nobody in the developer’s company had ever thought about. But that does not replace documentation, it merely adds other viewpoints to it.

        If I, as a technical communicator working for the production company, take over information from the community and put it in the official documentation for the product, I thereby take responsibility for the correctness of the information. That makes me accountable in case something is wrong and damages result from that incorrect information.

        I am referring to business areas where the technical documentation is vital to correct use of the products. Any company using wikis for their official documentation is obviously not working in those types of domains. That is the most important point I was making in my comment. And yes, I do exaggerate sometimes, just like you do in your original article. Just to show another viewpoint.

  21. Even fairly complex intranets often don’t have proper budgets for documentation, and I’ve felt the resulting pain. Instead of less documentation we need more documentation. What I think needs to happen is a deprofessionalization like what we’ve seen in a lot of other industries (e.g. journalism, photography,…).

    But deprofessionalization requires new tools that help amateurs leapfrog the professionals (e.g. Twitter and blogs, cheap digital cameras,…). Does that result in the death of technical writing? Definitely not! In deprofessionalized industries we see how the old guard still survives and some of the top performers actually thrive and leverage those new technologies to provide a better service.

    But I think we still have a way to go to make this possible for technical communications. We will need better tools than wikis to make crowdsourced documentation work properly.

    We are working in this space on an open source software that makes it trivial for people to record a Task for an online application. This is a demo of how it works: :)

  22. Owning a technical writing services business means we need to have customers that are willing to pay for technical writing. The future of the profession is very much something that’s of importance to us. Indeed, one of the first articles we wrote when we started back in 2002/3 was on the death of the technical communicator.

    Here’s my two ha’peth-worth:

    1. In the future, businesses will still need someone to check they don’t run out of money, someone to persuade people to buy products, and someone to explain how to get the most out of a product, service or system. There will always be a need to explain technical ‘stuff’, and this will be mostly to a non-technical audience. A great deal of that will be best explained using words.

    Products have got simpler and users have got better, but this can push products into being seen as a commodity. Most apps, remember, are free of charge. This means businesses start adding features to differentiate themselves, and the complexity creeps back in (the other ways are to have a great brand or a great design).

    2. The model we have for technical writing hasn’t really changed since Minimalism was introduced around 1989. So although there will be a need to explain ‘stuff’, the traditional model may not be appropriate in many situations today.

    3. We’re seeing some organisations move towards a design-led approach to User Assistance, to respond to points 1 and 2 above. Some are moving technical writing to the front of the development process, rather than leaving it to the end. Some are making the Technical Authors are giving responsibility for all of the words (on the UI, in the documentation, even in the user forums). They are repositioning the Technical Writers as Information Experience Developers, Information Developers or a similar title.

    However, job titles are tenacious things. Banker comes from the Middle Ages Italian word for long bench. The benches are long gone, but the title remains.

    4. In our experience, very few Documentation Teams measure the value of what they produce. They tend to be measured on productivity, which leads to the trend towards creating the same old thing more efficiently. This is the trap Ford fell into with the Model T, where they ended up building a car that fewer and fewer people wanted to buy. This is in stark contrast to Content Strategists, who spend their lives elbows-deep in analytical spreadsheets.

  23. But most importantly, XML is a tool for allowing content to be pushed in different sets to different channels, the opposite of what Mark Baker suggests: ” is a publishing platform designed to support what we might call the conduit of authority model of communication. That is, qualified experts write, structure, and assemble discrete information products which are then published them as a unit.”

    There’s no practical reason we can’t have collaborative tools and XML at the bottom–except no one’s quite built that yet.

    • Actually, Mysti, pushing different content to different channels is typical of the conduit of authority model. The authority wants to have multiple conduits so that it can push different messages to different people, and thus control the conversation to a greater degree. Every politician wishes they could say one thing to labor and another thing to Wall Street.

      The real problem with this, though, is not finding a way to deliver different content to different conduits from the same source. The problem is that the conduits are breaking down. It is now the reader, not the writer, who decides what information they will receive.

      Politicians used to be able to promise one thing in Dayton and another thing in Charleston. No more. Today people in Dayton will hear anything that affects Dayton, even if it is spoken in Charleston.

      We are entering a world without channels, a world in which your page will show up in the search results of whoever the Google search algorithm thinks might be interested in it. The value of a technology whose purpose it to create content for different channels may be questionable in such an environment.

  24. Pingback: Complex tools versus simple tools | I'd Rather Be Writing

Comments are closed.