The future of tech comm is developer doc

I attended an STC presentation the other week by Andrew Davis (one of the most helpful recruiters in Silicon Valley) on Ageism and Today’s Technical Content Developer.

Ageism is simply bias against the capabilities of older people in the workplace, and it’s pretty rampant in Silicon Valley. Most programmers are twenty somethings who live on Red Bull and free company food, who roll into at work around 10am and leave at around 7pm in the evening, only to play video games until 1am. These digital natives, who speak and breathe code, whose neuro-electrical synapses seem to be powered by the Internet, often look at someone beyond 50 as outdated, technically shallow, and too fixed in his or her antiquated ways.

There was a lively discussion during Andrew’s presentation, and the topic veered into the market trends. As I have heard so often, many attendees pointed out that jobs for technical writers are drying up. Joe Malin, an API technical writer who had previously been working at Google, noted that while jobs for end user documentation are drying up, jobs in the developer documentation space, such as with APIs, are exploding.

Andrew agreed that this is the case. End users are expecting more familiar interfaces, increased usability, and general intuitiveness in applications. If end users need to consult a help file to use your mainstream application, you’re probably in trouble.

But the technology behind those applications is getting increasingly complicated. More than ever there’s a need for help for developers. The number of programming languages, technologies, and platforms has made the developer’s world a tricky landscape to navigate.

According to John Musser, who runs the Programmable Web, poor documentation is a major obstacle in learning an API. In John’s presentation 10 Reasons Developers Hate Your API, the #1 reason is as follows:

The number one reason why developers hate your API: Your documentation sucks

The number one reason why developers hate your API: Your documentation sucks

John knows APIs well. The Programmable Web maintains a directory of all the open APIs on the web, and there are more than 11,000 of them.

Is there a better fit for technical writers in Silicon Valley, regardless of age, to get both foothold and influence in tech comm than to provide solutions for the #1 problem with API documentation?

Unfortunately, many of the tech comm solutions that have been received the bulk of attention in the tech comm industry don’t address API documentation with the care and attention one might hope.

Tech comm traditionally focuses on single sourcing, content-reuse, and structured authoring. This facilitates translation, supports large tech writing teams, and helps reduce time spent formatting.

Most of the APIs, however, aren’t translated. They aren’t delivered as printed material. And they require advanced developer knowledge to properly document. Writing code samples for 4 different languages requires familiarity with code.

Most of the API documentation sites I’ve seen are built on attractive and easy-to-navigate websites. For example, take a look at the documentation for Stripes, or Twilio, or Klout, or Constant Contact. (I’m planning another post that surveys around 50 or so API doc sites. )

To thrive in the API doc space, are the skills you need “structured authoring” or expertise at “single sourcing”? I don’t think so. In fact, structured authoring techniques are somewhat antithetical to the needed collaborative authoring with engineers. The developer doc skills you need are a bit different:

  • Knowledge of programming languages (C++, Java, Python, JavaScript, Ruby)
  • Ability to publish on a front-end web platform
  • Ability to collaborate with twenty-something engineers in a productive way

REST APIs actually have a structure that you can use to make the documentation interactive. Check out RAML and Swagger. I haven’t explored these technologies yet, but when you consider the needs for REST APIs to demonstrate calls and responses, parameters and other options, the traditional tech comm strategies using things like DITA don’t provide the needed structure in any special way. Beyond a table, there’s nothing in the concept, task, or reference spec that addresses the needs of API documentation.

Granted, there’s a lot in basic technical communication that does go a long way in creating developer documentation. Learning how to communicate complexity is our speciality, and when you use visual communication, copious examples, readable formatting (lists, subheadings, small paragraphs), clear sentences, defined terminology, progressive disclosure, sample exercises, demo pages, and more, you’re doing the bulk of the work of communication already.

Yet it seems more than communication skills are needed to thrive. You’ll always be at a disadvantage to those who speak code fluently. Those 20 years of writing experience mean nothing if you can’t quickly articulate what a class or function does.

I see the developer doc space as one of the great opportunities before us, and one that the tech comm community can tackle. Imagine if technical writers could provide solutions for making API documentation much more usable? Imagine if we could leverage established techniques of our trade for getting people up and running quickly with developer tasks? Imagine if we had modern front-end platforms that made it easy to consume API and other developer information? Imagine if we had ways to collaborate with non-writers on content and still publish complex deliverables?

API documentation is a topic I’ll be exploring on my blog for a while.

Madcap FlareAdobe Robohelp

This entry was posted in API documentation on by .

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS, email, or another method. To learn more about me, see my About page. You can also contact me if you have questions.

25 thoughts on “The future of tech comm is developer doc

  1. Mark Baker

    Hi Tom,

    I agree with you entirely about end-user docs vs. developer docs (thought we might perhaps extend that to documentation for technicians, or which software developers are only one breed). As I have written before, I see this simply as a return to the pre-tech-boom norm. Ordinary consumers don’t buy stuff that requires extensive documentation except in times of extraordinary change. Tech comm’s natural audience is the technician, and we are getting back to this natural state of affairs.

    About the relevance of structured writing to developer/technician documentation, however, I could not disagree more strongly. You could get away without structured writing in the consumer tech comm space. You can’t get away without it in the developer/technician space.

    The entire SGML movement was born in the areas of aerospace and defence, areas that required highly precise, highly accurate, highly available content. Structured writing was developed to meet those needs, and they are the same needs we find in the API documentation space today.

    The problem is, the term “structured writing” has become associated with publishing and content management functions like single sourcing and reuse — things that do matter in the consumer space and generally matter less, as you point out, in the developer/technician space.

    DocBook was the first culprit in this regard. There is actually nothing really structured about DocBook. It is mainly an abstract representation of the publishing artefacts of a book. DocBook is publishing technology, and it painted structured writing with the publishing technology brush.

    DITA, though it does provide the capability to define real structure through specialization, has not really helped matters, as the main focus has been on reuse — a content management function that has little to do with content structure, and which is actually more easily served by generic structures. (This is why DITA uses specialization as it mechanism for defining structured, so that structured things can behave like generic things for purpose of reuse.) DITA, as commonly implemented, is a content management technology and paints structured writing with the content management brush.

    But real structured writing is not about publishing or content management, it is about the consistency, correctness, and completeness of content, and about the automation of content compilation, extraction, and validation. It achieves this through structures that model and enforce the semantic and rhetorical structure of content.

    Developers have no trouble working with structured content of this kind. This is exactly how they code and data they work on every day is structured, so they are thoroughly familiar with the approach and understand it well. Indeed, they are used to documenting things this way, using things like JavaDoc. (The kind of structured writing that exposes all kinds of content management and publishing semantics drives them nuts, however, because they don’t know or care about those things.)

    The problem is not that developers can’t do structured content. The problem is that tech writers have been doing structured content wrong, mostly because they have been trying to make it behave like desktop publishing. Developers won’t do that, but nor should tech writers. The increasing importance of developer/technician documentation is a strong sign that we should be learning to do structured writing correctly.

    1. Tom Johnson Post author

      Mark, thanks for commenting. I agree that structured writing in most tech comm contexts ends up being about DITA and relates to publishing technologies, mostly content re-use single sourcing. You mentioned structured content within Javadoc. You’re right that the information there is highly structured. There’s a specific syntax and format to annotate the code in a way that generates documentation.

      Overall, your comment here is really interesting: “You could get away without structured writing in the consumer tech comm space. You can’t get away without it in the developer/technician space.” It would be interesting to see you expand on this in a post. What’s more difficult is breaking free from the mindset that structured writing = dita, docbook, or s100d and nothing more.

  2. Scot Marvin

    Great article, Tom. This is a topic I’ve been thinking about a lot. I keep reading that technical communications is dead and how everyone should go into marketing or become a content strategist or some nebulous content manager.

    Maybe traditional techcomm is dead. But in this age of the platform, with the advent of PaaS and IaaS, there’s just a new world of content badly in need of folks who can create it, edit it, and format it. APIs probably won’t be documenting themselves, this side of Skynet. Until they do, there will always be a need for writers.

    1. Tom Johnson Post author

      Scot, thanks for commenting. I’ve been hearing that tech writing is dead for the past 10 years. However, there are still plenty of end-user jobs around here, at least in Silicon Valley. I’m in the middle of transitioning to a new job, and I had solid opportunities at several companies that would involve writing end-user doc. But I opted for one writing more developer doc because it’s so hard to learn these skills outside of an actual project and corporate context. Anyway, I do know that there are a lot more dev jobs than end-user jobs, but it is hard to really qualify for them without the dev knowledge/background.

  3. Craig

    I am interested in learning more about developer documentation, especially in how technical writers like myself can learn it on their own.

    1. Tom Johnson Post author

      Fortunately there are many resources online to learn coding now. One of my favorites is safariflow.com. $29 a month is almost nothing. It’s the many hours required to try to parse through and understand the information.

  4. Neal Kaplan

    Great article, Tom, and great discussion.

    The last time I hired a tech writer, it was to document a new REST API (and almost everyone told us to “make it look like Stripe’s”). I’m not documenting an API right now, but I (or another writer) will be working on that within a year. Our product is complex enterprise software, so we also need product documentation, but a full time techcomm person in this role will need to be able to write both.

    We not only need to learn to code, but as Mark commented, we still need to figure out the best way to document that code. I’m looking forward to reading your thoughts on this.

    1. Tom Johnson Post author

      Hey Neal, re Stripe’s documentation, I actually asked someone at Stripe what they’re using. They said, “The format and style is borrowed (with permission) from the CoffeeScript documentation, but the software generating the documentation was built in-house. Something you might want to look into is Docco: http://jashkenas.github.io/docco/.”

      Personally, I’m not convinced that a custom-built system is really so much better than something like WordPress. But more on that later.

      As Robin pointed out, the API is just reference material. The tutorials are still needed, and there’s not really anything like javadocs or sandcastle that’s going to auto-generate the tutorial information from code itself.

      I’m planning a lot more posts on this topic, so stay tuned.

  5. Alexandra

    Hi Tom,

    I just read your series “From Overlooked to Center Stage” and after reading this article, it seems that there is a difficulty in technical communication to define a definition of the profession and set of goals to carve a sustainable career path. I agree that the end user writing positions are dwindling and I think that many interested writers, regardless of age, want to evolve with the field but it feels impossible. The market is changing but, unless you are blessed with a supportive company/manger and allowing environment, there isn’t an easy path for the rest of us to keep up. Adobe’s products are expensive for personal use and a co-worker of mine went to a sponsored “Adobe Day” where the Adobe employees confirmed that the Tech Comm suite is not, and will probably never be, included in the Creative Cloud. Essentially, access to the tools and skills that give us an edge are seemingly becoming more and more exclusive. Maybe this is Darwinism coming into effect but, like most other professions, there should be paths and stepping stones in place to help writers grow. Instead, it feels like I’m standing at the edge of a wide lake figuring out how to cross to the other side without a boat in sight.

    Perhaps the field is too dependent on personal situations. Like you mentioned in your “From Overlooked to Center Stage” you learned QA, debugging, and other helpful skills because you were able to fall into them easily and everyone around you accepted it. I started learning content management by creating a robust document repository on SharePoint. A writer involved heavily with project management documentation may easily become a PM. But what happens when you’ve hit the ceiling of your scope? What happens when learning Captivate is considering not a technical writing function, if your environment doesn’t have a lot of reuse, or you can’t get approval for highly specific tools for structured authoring?

    Should the profession be defined by your current work environment? Is part of the problem that the field is too widely defined? When someone says “I’m a network engineer” it’s very clear what they do and their role within the IT infrastructure. Tech comm is writing, programming, e-leaning, project management, information architecture, information development, and lot of other skills that doesn’t fit under any common career structure. Don’t get me wrong, I love that the field has a lot of avenues. But maybe we’re stretched too thin which is hurting us, rather than helping us.

    1. Tom Johnson Post author

      Alexandra, thanks for reading through that series. Re access to tools to keep up, you can learn DITA relatively inexpensively. The only tool you’d need is OxygenXML or something similar. The Tech Comm Suite provides some good tools, sure, but I actually haven’t seen too many jobs requiring Robohelp. Framemaker, yes, but not as many as DITA. Re video creation tools, Camtasia Studio is superior to Captivate in many ways and substantially cheaper. Mostly, the problem with keeping up isn’t so much the cost as the time required to learn. And you need to be in working environments to get hands-on experience with the tools and technologies.

  6. Amruta

    I don’t believe it. I just typed an email to you about the same topic! Even the subject line is the same! We have our Regional STC Conference in June, and I am planning to present this topic and wanted to ask for inputs about it. And now you put up this amazing post…Law of attraction at its best :D

    1. Tom Johnson Post author

      Amruta, glad to hear you’re presenting on this topic. Can you share any of the details of your planned presentation with me? I’m also doing some podcasts on this same topic.

  7. Pingback: Tech Writer This Week for June 5, 2014 | TechWhirl

  8. Robin Whitmore

    Hi Tom,

    Don’t forget that API documentation is only one part of the Developer Content package. While the API doc normally documents the “whats” (what is the api, what are the parameters it takes, what are the objects it returns, etc.) it very rarely provides any “whys.” Developers also needs content that explains why and when they’d want to use the APIs, and more importantly, how to string the APIs together to create a robust piece of software (or whatever else they are creating). Now I know many developers will say they don’t need this, but when they don’t have it, you’ll find them posting to forums and searching the web, often getting half- answers, and usually getting frustrated and wasting time. If they have the right documentation that gives them the big picture answers, and it works, you’ll find they become very appreciative!
    We currently use structured Frame and a form of DocBook to provide this type of content, and now we’re moving to DITA. Unfortunately, I don’t think DITA alone will allow us to provide all the whys and whens with plenty of links to the whats in a form that developers will find easy and intuitive to use. I think we’ll end up with a DITA/EPIPO hybrid, and perhaps instead of providing a book, the content will be interspersed in a hosted demo showing what the code can do. Some sort of topic-based content is the only way we’ll be able to provide it. And it will have to be structured so that all writers can reproduce content for different areas of our product, and so that it works in predictable ways outside of the book paradigm.
    All this to say that I think structured content does have a place in developer docs, that there are plenty of content types other than APIs that need to be created, and that it will take creative, out-of-the-box technical writers to determine the best way to create, structure, and present that content. So I agree wholeheartedly that Developer docs are going to be a great space to be in!

    1. Tom Johnson Post author

      Robin, thanks for commenting. I wholehearted agree with your comment here. I think I tend to place too much emphasis on API documentation instead of developer documentation in general. One great example of the needed programming tutorials (non-API doc) that should accompany API reference material is the Java Tutorial from Oracle. I think it would be quite difficult to figure out all the details of an API without some kind of more narrative, explanatory material. And for that, the traditional tech comm approaches, whether DITA or a HAT, probably work well.

      By the way, what is EPIPO? I didn’t catch that one.

  9. Debbie M

    I want to thank Mark for saying:
    “I see this simply as a return to the pre-tech-boom norm. Ordinary consumers don’t buy stuff that requires extensive documentation except in times of extraordinary change. Tech comm’s natural audience is the technician, and we are getting back to this natural state of affairs.”

    I work for a company that makes real things you can touch with a complicated and highly customizable deployment process and hundreds of inter-dependent configuration options. I think there will always be a need for professionally written technical documentation in this area.

  10. Pingback: Structured Writing is Essential for Developer Docs | Every Page is Page One

  11. Linda

    Hi Tom.
    So I’m drinking the KoolAid so to speak: I’m learning code online, reading the right books, but I have zero experience in API documentation on my résume. How do I get a potential employer to hire me? I’m tempted to go back to school just to get some sort of official schooling certification—however I’m not totally convinced this is the right way to go.

    I’m enjoying all your posts/podcasts about the topic of API writing—they’re filled with so much useful info. Thanks!

    1. Mark Baker

      Linda,

      More and more the application forms for programming jobs, and a variety of other tech jobs, including writing developer docs, are asking for the address of the applicant’s GitHub repository.

      GitHub is a public repository of open source code which tends to focus on works in progress and encourages people to fork other people’s code and to contribute to projects that interest them. In other words, you don’t have to be finished before you can share.

      The point is, when it comes to demonstrating programming skill and knowledge, what you can show is often more important what what paper credentials you possess. (There are growing complaints that people graduating with computer science degrees these days can’t actually code.) The best way to show what you can do is to show what you can do.

      Consider, for instance, Sarah Maddox project, Tech Comm on a Map (http://sarahmaddox.github.io/techcomm-map/). This is the way a tech writer can demonstrate that they grok APIs.

      My GitHub repository, by the way, is https://github.com/mbakeranalecta.

  12. UTPAL

    Not everyone likes coding and I feel one cannot push/force himself/herself to learn programming. You cannot do this (everyday) unless you really enjoy the code part. The writers who actually like the code part should try API/Developers doc.
    Another option is to try writing highly complex docs in the Networking/Storage/Clustering/Wireless domains and get certified (VCP/CCNA/Juniper etc).
    That will differentiate you from the crowd. In the networking/storage world, the action is in software now. For example, SDS, NFV, SDN etc. Datacenters are getting complex and mobile/social media/cloud are making it even more complex.
    I think, this route will equally rewarding.

Comments are closed.