Category: Technical writing

Yet another study is out, this one from UC Berkeley: Most developers think we should spend more time on documentation, showing that developers, when asked, say that they want more documentation, or, in this case, need to spend more time working on (writing?) the documentation for the software they use and write. The list of related studies is long (by software-documentation-related-studies standards, anyway), a few of which I mention in A brief history of API Docs and in my bibliography.

I understand the the desire to ask developers (over and over, now) questions like “do you have enough documentation?” “what’s wrong with the documentation?” “What do you want to see more of in documentation?” and so on, when those are the questions on your mind. However, that type of question has been asked for over 15 years and the answers haven’t changed.

At this point, we should just assume that,

Developers will always tell you that they want more documentation.

They always have and they always will.

If you want to know why they express this need for more documentation, my hypothesis (based on previous research) is that it’s…

Because developers can’t find the documentation they need when they need it.

Continue reading “Do we want more docs, or just better docs?”

While researching my dissertation, I came across a quote that resonated with my experience as a developer and at the same time troubled me as a technical writer (so, you’ll see me quote it frequently). It’s from a study published in 2009¹ about how developers used documentation while completing some programming tasks.

“Several participants reported using the Web as an alternative to memorizing routinely-used snippets of code.”

Just today, this idea was addressed directly in this tweet:

What do you Google EVERY. SINGLE. TIME. and never just memorize?
{ author: @bendhalpern }https://t.co/sKGmchv5tN

— The Practical Dev (@ThePracticalDev) October 20, 2017

The tweet resulted in this thread. It’s early as I write this and there are only 16 responses, but I expect this to grow.

Thoughts and musings

From a research perspective, it provides a great collection of cases in which documentation is serving as an offline, community memory that many developers share–more evidence of what Brandt et al. observed in their 2009 study.

From a documentation and usability perspective, it’s a sort of rouges’ gallery of usability fails. Flipping through the responses, it’s interesting to see the different ways that usability challenges have been met by users of the tools.

For example,

• Mnemonics, in the case of how to use a tar file described in this thread. The conversation eventually refers to this doomsday scenario, so those mnemonics could save the world, some day.

  

• Creating an interpreter to translate English(-ish) to regex (Regular Expressions) in this thread. Other comments also refer to regex a the variety of places on the web that try to clarify its opaque notation.
• Community-sourced documentation was a method described in this thread. Any user of Unix or Linux is familiar with its man pages. This comment talks about simplified versions of this documentation being collected at TLDR pages. According to the site, “TLDR pages  are a community effort to simplify the beloved man pages with practical examples. “
• Redirection to StackOverflow in which StackOverflow is the community-supported documentation is another way developers deal with common, but not common-enough to memorize, cases as this comment describes.

What does this mean to technical writers?

There’s a recurring complaint among technical writers that no one reads technical docs. This conversation is evidence that if a feature is useful enough and unintuitive enough, that people will read them (or create work-arounds for them). For self-help content in general, however, I’m not sure that having a lot of documentation access is a worthwhile goal when it’s the result of a larger issue (e.g. a lack of usability). In fact, such traffic is often a clue that something needs attention, either in the product, the documentation, or both.

If, for whatever reason, you can’t make the product easier to use, you can use this list as a source of ideas to apply to your technical documentation strategy and help your readers.

---

¹ Brandt, J., Guo, P. J., Lewenstein, J., Dontcheva, M., & Klemmer, S. R. (2009). Two studies of opportunistic programming: interleaving web foraging, learning, and writing code (pp. 1589–1598). Presented at the Proceedings of the SIGCHI.

I was exploring Google Trends to see what was happening with tech comm and related terms and found this.

As an added bonus, if you click on Google Trends at the bottom of each image. you can open up the query in the Google Trends site and play with the variables.

Tech Comm ain’t what it used to be

Technical communication and tech comm have been declining in popularity over time. The highest point on the chart is represented as 100 and the rest of the data being relative to that. This chart shows that, the terms dropped in popularity until about 2007, after which they remained relatively stable, except tech comm continuing a slow but steady decline. The joined term, techcomm is even less common, so I omitted it because it ranged from only 0 to 6 over this time period.

Technical communication has annual peaks of activity, which could correspond to TC-related conferences. (I don’t have a database with which to correlate them, so it’s just a hunch.)

What’s moving up?

Continue reading “Charting the popularity of technical communication”

I just launched TC Myths, my site in which I’ve collected all the myths about technical communication that I could find.

Wow!

It started out as a quick lit. review, but the list grew more quickly than I expected (or imagined). I originally thought the list of myths would result in a duplicate of a similar list at UX Myths and then that would be the end of it. As it turns out, there is very little overlap. It also turns out that TC Myths are (or have been so far) much harder to research, compared to the UX Myths. The myths are also mysterious, which is why I’ve opened it up to comments and contributions.

I’m trying to understand why Technical Communication has (by my last count) over 70 different myths! Do we really need that many?

So, what does it take to be a TC Myth?
Continue reading “Tech comm myths site is live”

The good news is that Google has released the Google Developer Documentation Style Guide . The bad news could soon be that Google released the Google Developer Documentation Style Guide .

It doesn’t have to be that way.

I’m delighted to see that the style guide includes, albeit below the fold, the advice to:

Remember that everything in this guide is a guideline, not a draconian rule.

Personally, I think this caveat should be on every page as part of the chrome, but at least it’s in the introduction. Unfortunately, my cursory review of the guide shows that the rules provide little context to help readers (in and out of Google) decide when would be good time to break a given rule and what the consequence or effect of that might be. But, this is not new. It has been a deficiency in technical communication guidelines and best practices that I’ve complained about for several years now. Maybe in v2?

Getting started

The highlights are a good place to start and provide a short cheat sheet of rules that are relatively universal and, while they don’t provide any resources or background for why these are good practices, I’m familiar with research that supports most of the suggestions, but I’m an outlier.

Hey, Google editors, for v2, please provide links to the background and research behind these guidelines to help readers–that is, the technical writers who will be applying these principles–understand why these are good practices and when they might want to make exceptions as you suggest in the opening caveat.
Continue reading “Google Developer Documentation Style Guide has been released”