Including excerpts from interview with Jim Tallman, retired hardware engineer, software engineer and technical manager.
Regardless of what the general public may think, we all know that most software engineers do a heck of a lot more than just typing code all day. There are a plethora of skill sets, both technical and soft, not directly related to writing code that well-rounded software engineers possess. One of these skills is technical writing. You may be wondering, what is technical writing exactly? Literally, technical writing is “writing or drafting technical communication used in technical and occupational fields, such as computer hardware and software, engineering, chemistry, aeronautics, robotics, finance, medical, consumer electronics, biotechnology, and forestry.” (Wikipedia, 2022). In other words, technical writing works to express technical ideas in an efficient manner to both experts and non-experts.
The writing aspects of software engineering are often overlooked by aspiring engineers, but they are of crucial importance in a variety of ways. Through an exploration of a personal interview with Jim Tallman, a retired hardware engineer, software engineer and technical project manager for 34 years at Tectonics and a variety of online resources this article will explore why technical writing is important for every software engineer. Additionally, I will take an in-depth look at a technical document that is crucial to successful software engineering, a software requirement specification.
An Important Pillar of Software Engineering
Technical writing shows up in many different places in software engineering from an individual level to interacting with the customer and everything in-between. The amount and type of technical writing that you both
use and come across in your career will depend on how close to, or how far from the user, or client, your specific job is. Regardless of that, there are some areas that almost all software engineers will run into the need for not only using technical
writing, but understanding it and knowing what good technical writing looks like. From my own experience as a software engineering student some of the most common places where technical writing shows up are:
* Planning your programs
* Pseudocode
* Documentation of code
* Communication
-between team members
-with instructors, or leaders
* Online communication
-emails
-Forums
-Discussion boards
* While sharing, or gaining new knowledge
-Instruction documents
-Textbooks
-Blog posts
In my interview with Jim Tallman, he mentioned more specific examples of where software engineers, or anyone working in the industry, may use technical writing. These include:
* Software requirement specification documents
* Writing, or helping to write patents
* Publishing articles on software, or new technology
* User’s manuals
In his article, The Importance of Writing for Software Engineers Ben McCormick discusses his personal experience as a software engineer and in the tech industry. He makes additional, more abstract points about the importance of technical writing as a software engineer. These points include:
* you will write every day
* the ability to explain complex topics will set you apart
* writing will help you find a better job
* remote work increases the importance of writing
* your career trajectory will depend on your ability to influence and persuade
*writing skills translate to writing code
This article spoke to my own experience as an aspiring software engineer. In the last year and half of taking computer science classes I have written every day. I can attest to the importance of focusing on the pillars of good technical writing to successfully navigate
the various tasks that are given to me. I also know that like many people, I can learn to code, but I have a secret toolbox of skills, many of them related to technical writing, that will help me to stand out in a crowd of programmers.
Software Requirement Specifications: Technical Writing in Action
A software requirement specification (SRS) is a “formal report, which acts as a representation of software that enables the customers to review whether it (SRS) is according to their requirements. Also, it comprises user requirements for a system as well as detailed specifications of the system requirements”(javaTpoint) In my interview with Jim Tallman he spoke about the SRS being one of the most important and difficult documents that he had to write. The importance of an SRS stems from its purpose of allowing the programmer to have a roadmap written in plain English that is easily changed well before any coding is actually happening. The ability to easily change the SRS helps to avoid spending time and other resources building something that you may, or may not end up using by the end of the project. Although easy to change, Jim expressed that the most difficult part of a SRS is the balance of knowing when to stop writing and start building your program. “[its]… a very delicate balance of when do you stop writing and start building because you can’t design every detail at step 1s a tough judgment call because you can always say ‘why didn’t you develop that part, or think that part through’ (personal interview, Jim Tallman, 2022). In some cases, such as in Jim’s position, this document will also be reviewed by nearly all departments including, but not limited to, marketing, manufacturing, repair and service before any work begins further complicating the problem of knowing when to stop writing and ask for approval to get started, or when to keep going. As the basis of the entire project and with such a wide variety of people with varying technical backgrounds and experience reading through the SRS a clear, concise, correct, accessible and relevant document is the only one that will be of real use. (personal interview, Jim Tallman, 2022). When thinking about what makes an excellent SRS and what makes excellent technical writing, there appear to be many crossovers. In their article Software engineering: Software requirement specifications javaTpoint states that an excellent SRS has the following properties:
*Completeness
*Consistency
*Unambiguousness
*Ranking for importance and stability
*Modifiability
*Verifiability
*Traceability
*Design independence
*Testability
*Understandable by the customer
*The right level of abstraction
And the following essential properties:
*Concise
*Structured
*Black-box view
*Conceptual integrity
*Verifiable
According to Panangipally (2020) the following characteristics are what distinguish excellent technical documents:
* Correct
* Honest
* Clear
* Accessible
* Comprehensive
* Accurate
* Concise
* Professional appearance
* Relevant
* Well-structured
Grow and Utilize you “Unicorn Skill”
Putting an emphasis on your technical writing skills can truly make you a unicorn in a crowd of donkeys. Software engineers don’t just make their careers in front of a computer screen, but through collaboration with many different people and in many different forms. If you’re already a strong writer, even better, hone in on those skills along with the coding skills that you will inevitably pick up. Capitalize on the non-technical skills that you possess and push back against the idea that all great coders work alone, in dark rooms and possess no other skills other than coding. Everyone has something to bring to the table and everyone can work to grow and learn new skills that will take their careers to the next level. For software engineers technical writing could very well be that skill.
Bibliography
The importance of writing for software developers. JSON. (n.d.). Retrieved June 12, 2022, from https://benmccormick.org/2019/03/02/the-importance-of-writing
Panangipally, A. (2020, October 23). Characteristics of effective technical content. ibruk Consulting. Retrieved June 12, 2022, from https://ibruk.in/characteristics-of-effective-technical-content/
Personal Interview, Jim Tallman, June, 04, 2022.
Software engineering: Software requirement specifications – javatpoint. http://www.javatpoint.com. (n.d.). Retrieved June 12, 2022, from https://www.javatpoint.com/software-requirement-specifications
Why every developers should know technical writing. IEEE Computer Society Why Every Developer Should Know a Bit of Technical Writing Comments. (n.d.). Retrieved June 12, 2022, from https://www.computer.org/publications/tech-news/trends/why-every-developer-should-know-a-bit-of-technical-writing
Wikimedia Foundation. (2022, April 21). Technical writing. Wikipedia. Retrieved June 12, 2022, from https://en.wikipedia.org/wiki/Technical_writing
E.A.R PDX 
Leave a comment