Embedded Files
Important Terms
Important Terms
Programming language: A way to easily allow people to tell a computer what to do.
OS: This is an abbreviation for operating system. The operating system is what tells the physical hardware for your device what to do based on the input you give it.
Variables: Used to store pieces of information within the code to use later.
Syntax: The specific keywords used that the programming language assigns to different tasks.
Methods: Specific sections of the code that can be used in multiple places and multiple times.
Open Source: A project where the developer lets people see and download the original code
Bugs: Specific to programming a bug is an unintentional side effect of the code which can degrade user experience.
What is Software Development?
What is Software Development?
Software development is quite simple in concept. Essentially someone learns a programming language and then decides to create an app. Apps are what power everything we do on the computer today. Every video game, social media platform on your smart phone, and even text messages are all examples of apps. Software development even goes further than that. Your phone runs on an OS, that OS is just software that someone wrote using a programming language. Software development has so many different examples that all boil down to someone using a programming language to make it work.
Technical Communication in Software Development
Technical Communication in Software Development
To show technical communication in this field there is a really easy way out by using stuff like emails, project reports, and other standard development. Instead of. There are three examples that will be provided, two of them will be how two software developers communicate with each other and the third will be how the software developers communicate with the users of their software.
The first way that software developers communicate with each other is with comments within the code itself. The intended audience for comments within code is other developers thus assuming some level of programming and syntax knowledge. There are two main types of comments which are single-line and multi-line comments. Comments exist to allow the developer to easily explain what a particular part of the code does within the code itself. To the right you will see two images. One image has comments which are denoted with “//” and the other doesn’t.
These examples are simple pieces of code I write specifically to show how comments can be used. To another software developer the comments in these examples would be useless. For a more complicated project they would be necessary as it is very hard to know exactly what does what, especially when there are multiple variables. If you were to try to understand the code example given it would be hard especially if you don’t know anything about code. But with the comments it can be easier to follow what is happening. Take for example the last comment that was put in the code on the right. Without knowledge of the syntax, there is no way to know that it just loops through the code inside of it. Comments are most effective when they are detailed but not used in excess as too many comments can clutter the code and actually make it harder to understand.
(Coding example without comments written by author)
(Coding example with comments written by author)
(Code from a previous class written by author)
The second way software developers communicate with each other is code documentation. The intended audience for documentation is similar that of comments but it clearly explains custom syntax that is specific to the project. The example used here is Java Docs which is specific to the Java programming language. Documentation is basically taking comments, making them more thorough and better explaining the use cases of the methods in the code. Documentation is most effective when the project starts to get bigger and comments would be kind of hard to see in an organized way. The example given is only the documentation used at the header of project it was pulled from. One of the big parts of Java programming is making objects to do different tasks. Objects are essentially a container for the methods. One object can have numerous methods, and those methods can get complicated quickly.
Documentation fixes this by going object by object and listing the methods in the object. While listing the methods and objects a developer can write a bit of information about what the object is for and what the methods in the object do. With Java Docs the developer can have a documentation page generated that makes it even easier to follow. The Official Java Documentation is an example of exactly how the documentation page is displayed and organized (Oracle, n.d.). When reading through the documentation someone can learn what different objects and methods that are part of the programming language do. Along with the snippet of personal code shared there is an image of a small portion of the Java documentation page.
The third piece of technical communication is how developers communicate with the people using the software. There are so many ways that this can happen and of the most common ways for open-source project is a document often called “README.md” and most of the time gives instructions on how to use the project. The intended audience for README.md files is the user that will most likely not be going through the code itself and thus doesn’t assume any knowledge of programming. The example that will be used is mGBA which is an app that allows people to play Nintendo Game Boy games on their computer (mgba-emu, n.d.). The image to the right is a small portion of the README.md file for mGBA. As you can see it gives the system requirements, where to download, and the controls. Out of those three things, only the controls could be found in the code and that even depends on how the code wzas written. If you were to go and view the original project here and scrolled down, you would see how detailed that file really is. The best way to think about the README.md file is to compare it to an owner’s manual for a car. Both the file and an owner’s manual for a car give a bunch of information to fix common issues and explain the intended way to use different functions. Like an owner’s manual a README.md file is most effective when organized in a way that the average person could understand it.
(mGBA project README. Screenshot from mgba-emu (n.d.).)
How the Three Pieces of Technical Communication Compare
How the Three Pieces of Technical Communication Compare
How AI is Changing Technical Communication in Software Development:
How AI is Changing Technical Communication in Software Development:
As AI gets more sophisticated and more powerful it slowly puts less work on software developers. With the current AI that can be publicly accessed anyone can write code and the AI will often times add comments to the code for you. Upon request you can even get documentation and a README.md file generated in seconds. But code has bugs and AI can fix those bugs, but it will often create bugs unintentionally or use a less effective method to complete the task. Furthermore, AI can provide false information which sometimes can make it into documentation which makes it harder to follow what is going on. The biggest advantage to AI is going to be how it can more easily explain stuff in a simpler way to allow people to understand better. Overall AI has a positive impact on technical communication in software development for the sole reason of making it faster overall to write.
Recommendations to improve communications for clients in this field:
Recommendations to improve communications for clients in this field:
First will be recommendations specifically for comments in code. The easiest recommendation is to actually put comments in the code. So often people who are newer to programming forget to leave comments or leave bad comments. The best way to do this is to explain the point of the specific section of code. After explaining it you would go through and make it as concise as possible without leaving out important details. The second easiest recommendation is to assume the audience doesn’t know anything about your code except for the syntax. The Broad Institute of MID and Harvard has a coding and comments style guide available that is extremely helpful in further understanding how to make better comments in code (Broad Institute of MIT and Harvard, n.d.).
Next will be recommendations for both documentation and for communication between developers and users. The point of both of these pieces of communication is to make stuff easier to understand. The best way to make it clearer is to make sure that everything is as detailed as possible. It doesn’t matter if people should already know some of the stuff. It is almost always better to have excess details that some people might already know than to skip over them, which could make it harder for the rest of the people to understand it.
Lastly, there are a couple of recommendations that apply to all of the technical communication in software development. The most important thing is to always use the resources at your disposal. When writing anything that is explaining code you wrote it is important that people can actually understand it. Peer review, such as having a friend, co-worker, or even AI go over what you wrote can easily help find the unclear parts so that you can make it easier to follow and understand. The other thing is to always make the goal to explain thoroughly. For example, if it was a requirement by an employer or instructor, it is important not to treat the comments as a box you need to check. Rather, treat the comments like they are the assignment itself.
Page updated
Google Sites
Report abuse