I think your ability to get feedback depends from job to job. Depending on the scale of your product, you may have a big enough customer base that the technical writer stays at work the whole time. That rarely happened for me though.

Also change management is a big issue, even for web only applications. PM’s want the ability to decide how many updates the TW provides. Perhaps the point I’m getting at is that when the TW proposes something, it’s generally not going to be listened to. But when Support is proposing that the TW do some updates, PM is more likely to listen and act.

In my most recent job, everything went into an Entrack bug tracker, including support issues and feature requests. In fact, often customers entered their own tickets–but our customers are probably atypical (they are sysadmins).

As a result, I got to see all the outstanding issues, but things had to be reported and assigned to me first. This is not ideal; for example, usability issues are never reported–or more importantly, they are rejected by developers or Project managers because they are “user error issues.” As a technical writer I can anticipate a lot of user issues that a bug report will only hint at. But it’s a start.

Like I said, I’m basically agreed that the 2nd story is best case scenario, but I wanted to give insights into what it almost never occurs.

From a project management point of view, PM’s rarely let a technical writer continue working past release date. They don’t want to treat documentation as a continuous expense but as a one-time expense. Instead, PM’s assign the TW to another project. The time for revising comes before the next software release. I’m not defending this practice, merely pointing out that it may be unrealistic to think that PMs will budget for that.

As a practical matter, I’ve gotten around the problem by 1)pointing local help to a URL and getting permission to update on an as-needed basis, 2)getting to know support people very well, and 3)resigning myself to fixing these “user topics” in the update.

Re 1., “publish the update” means to update the help deliverables immediately. In smaller organizations, where there is less bureaucracy about change release procedures, it’s much simpler. The key, however, is to keep the help separate from the application code. In my situation, most of my help goes to an internal audience behind a firewall. We also have SharePoint. I use a file document repository on SharePoint as the location for my help. This allows me to update it on the fly. I give a link to the developer that points to my help on SharePoint. Soon we’ll move to single sign on, and then I may push for a separate help server for all our deliverables. The single sign on solves the problem of secondary logins when logged-in users jump from server to server.

Re 2, sure you would think the project manager gathering the requirements would be omniscient about customer needs, but unless you pull from all customers, there will be gaps. Think about how 300 people use Microsoft Word and Photoshop. If you pull requirements from a dozen people, how representative will their needs be of the whole? You can imagine that the way you or I would use Photoshop and Word will differ from the way a financial analyst or a high school student might use the apps. It’s impossible to know all the ways apps will be used. But yeah, the more you learn beforehand, the better.

(By the way, the fact that software goes through multiple versions proves that no matter how good of a requirements gatherer you are, customers will want something more or something different.)

Re 3., Printed matter becomes problematic here, but if you update the online help, you don’t need to notify customers. Your paper manuals might benefit from a timestamp. In my experience, most people search for their answers. They may download a manual becomes it feels like a security blanket, but it’s the online help that they search.

I do have a query though – how does the writer of scenario#2 deal with translations? Are the updates made to only the English version?

1. I’m not a help author, so I don’t know what “publish the update” means in Story #2, pgf 7. Does it include updating the application with a new set of help files? Is this a capability that a small (<$10M annual sales) sw dev company can provide to its customers? If not, how does the smaller company accomplish this?

2. Is it realistic to assume that the company’s tech writer is the company expert about how customers should be using the product? Is there a “product manager” or “product architect” in the company who is more of an expert in the product’s subject matter domain and marketplace? Would that person (rather than the tech writer) also have authored a product plan or specification that describes the product’s purpose, profiles of expected users, expected workflow(s) for using the product, etc.? The point here is, the more fully planned the product release is, the more successful will be the product’s reception by customers.

3. How often to “publish the update” to customers? Are they notified in advance? Does it occur according to some schedule? How often is too often?

Thanks for your post.

//Paul