Category: Technical writing

By this, I mean, should you describe in the formal documentation the way a feature actually works or the way it is supposed to work?

tl;dr: Yes.

There is a lot of research that says software developers (and, I would imagine almost anyone else, but I haven’t studied that research) expect the documentation to be accurate, so reference documentation should describe how something ACTUALLY works. If “how it works” changes, the documentation should be updated to reflect that. Simple, right?

Well, if a feature is shipped that (let’s say) still has some room for improvement, your accurate documentation will highlight that. A real fear in the hearts of some product managers is that your accurate documentation could turn some customers away saying, “we need something that does X and your product’s documentation says that it doesn’t do X (yet).” Your product manager will have to weigh the cost of that vs. the cost of having the customer build their system around your product expecting “X” only to find out that it doesn’t. A decision that could get your product into market and/or into an unflattering TechCrunch article.

The problem with reference topics (of almost any sort) is that, individually, they don’t do much and don’t get a lot of attention (except, of course, when they do). Collectively, they tell your customers how much you value their time and their business.

Recent events in the news bring this topic into the spotlight.
Continue reading “Should you document a bug?”

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”