Playbook

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).

Hand Drawing A Game Strategy

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.

Posted on October 28, 2017, in Digital, Literacy, Technology and tagged . Bookmark the permalink. 8 Comments.

  1. Thank you! One of my students described himself this week (we’re building resumes) as a “full-stack developer” but couldn’t come up with a definition of “full-stack”. My “go-to” source for all technological terms, webopedia.com, wasn’t much help. Now I get it.

    Maybe you could help my student by helping me understand more. Is “full-stack” more of a slang term – something one developer might say in conversation with other practitioners or is it a mainstream term?

    • Hey David! I usually use urbandictionary.com for any odd terms I am not familiar with. I’d consider “full-stack” a buzzword, but not sure if that helps. I’m not sure if anyone would really call themselves a full-stack developer, but then again maybe some do. As far as I know we usually use it specifically when job hunting, and will put it on our resume or apply for a job with that title. Specifically speaking, we usually use it to specify that we are not picky on doing front-end, back-end, or data-related development. Hopefully that helps some!

  2. Thank you for your insights here! I think your final paper could look at some of your workplace playbooks to offer a then/now overview of how quickly changes have been made in the field.

    Believe me, I also wish Spilka’s book would be updated. I checked again before this semester began because I was tempted to take the book off the reading list; however, it’s the only one out there that makes the attempt to focus on literacy and the TPC profession.

    • I think the book really gave some great perspectives! If Spilka does another book, an infographic or something could actually be really helpful in showing the evolution of technical communication responsibilities in the workplace.

  3. Hi Miriam,

    Thanks for sharing your insights. Your post was the inspiration for my post because I remembered software engineer was one of the jobs Brumberger and Later looked at and lumped in with technical communication.

    Thank you for sharing the information about playbooks. It sounds like you and your co-workers have a great system in place to work smarter, not harder. Do your co-workers outside your division/department use the content management system to find answers or do they contact you and your colleagues?

    I really appreciate your insights, especially because I am not in the field yet. Thanks again for sharing.

    Jennifer R.

    • Jennifer, thanks for your response! My co-workers and I do get a lot of requests to update the system with more information. Most of the System Engineers use our pages to help figure out integration points with other systems and the hardware teams. We are pretty good about keeping things up to date so they seem to trust that they can use our pages often, which is great. This is much more preferable to having hundreds of email chains asking for the same documents.

      “especially because I am not in the field yet.” Do you plan on going into an engineering field someday?

  4. I enjoyed reading your post. I thought the idea that your professors accepted the fact that computer science majors are not going to be gifted writers was interesting. I have a very similar background. I started off my undergrad career here at UW-Stout in the telecommunication systems (computer networking). I was in the program for a couple of years before switching majors. I can’t think of a time where we had to write any lengthy papers but we did have finals where we had to describe scenarios and how to fix the issues. In a very similar field we did rely on some writing.

    • Lynn, I think it’s awesome you did telecommunication systems! Even if you didn’t get your bachelors in it you probably still got some really great knowledge from it. I feel like the writing I did do in my CS undergrad was mostly graded on whether or not I got the message across. They didn’t focus too much on execution unless it actually affected what I was trying to say. It sounds pretty similar to your experience.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.