I found this week’s reading fairly awkward as it included software engineers as technical communicators. Software Engineer is a very misused term to begin with. Rachel Spilka’s book gave me the feeling that they used to be more document centric, but now they are more jack-of-all trades developers and managers, sometimes dev ops, and sometimes just programmers. A lot of software industry titles trend towards a jack-of-all trades type of job, hence the new title “Full-Stack engineer”. Full-stack engineers are usually developers who know all aspects of how to build a web application. Why pay multiple people when you can get just one that knows how to do everything? Initially, a technical communicator sounded like a far fetch in the software engineer’s knowledge tool-box.
When I was studying for my computer science degree, most professors seemed to verbally accept the fact that most of us were just not going to be gifted in the writing department. It was not a required or emphasized aspect even though I had a software engineering emphasis. In the industry, I cannot disagree with this either. Most legacy code I have worked on is not documented from the technical side at all. It’s not always because of talent or ability, but honestly the last thing most of my colleagues want to do after coding is sit down and write sufficient documentation for days after that. Additionally, one extra line of code has the potential to change most or all of a document on the system functionality. Documentation is looked at by our management as a nice to have, but it’s not a show-stopper if it’s not there. We are never interviewed on our writing skills. This first-hand knowledge made me raise an eyebrow when Spilka listed software engineers as technical communicators from the late 90’s to now.
What I realized part way through reading was that the documentation Rachel Spilka is referring to has changed just like how the job titles have changed. The documentation that a software engineer will generate is kind of dynamic and is not always a formal breed of documentation. Spilka states a couple times in the book that the job of technical communicators has changed audiences, that they have changed from being experts to novice. It seems to me that the responsibility for creating power user documentation has been assumed primarily by software engineers, architects and system engineers, while technical writers create more customer-facing or public documentation.
So, how do software engineers document? We document when we want to ensure that we don’t have to work more than we want. The documentation that we do produce is aimed at fellow engineers so we don’t have to repeat ourselves too much when new people are hired or start working on what we have already built. We also document for production systems for installation and troubleshooting guides for when things go very wrong. Both of these types of documents we call “playbooks” for our engineering sector. These playbooks seem very similar to the initial documentation that was created by technical communicators in the 70’s (Spilka, R., ed., 2010, 22).
We keep these playbooks on a content management system that is accessible by the entire company, so if they want they can just go to our page and try to find the answer to their question before talking to us. We can also receive comments on the content management system so that all discussions on the documentation are public. Sometimes the documentation just looks like notes and sometimes it looks like a proper installation document depending on its purpose. We also document even less formally by creating static and dynamic charts and graphs for the design of our system. These can be the most useful in explaining functionality to other software engineers. We also document by putting comments in code to explain exactly what we are trying to do algorithmically. All of these forms of documentation fully take advantage of the technological changes that have been granted to us to make technical communication more efficient.
This book was written in 2010 so I feel like a revision could occur to navigate even more technical communication responsibilities in businesses today. For example, System Engineers have a huge role in technical communication between all components of a technical product. I feel like this specific role could be very helpful in identifying where some of the technical communication responsibilities have been dispersed in today’s world. Spilka does mention that the content would probably be irrelevant for the types of companies that I work at. Additionally, every company is vastly different in how they incorporate technical platforms and integrate with engineering processes. I can only imagine the challenges Spilka encountered in trying to compile the history of technical communication.