Communications In Software Engineering

Abstract

In this article, I intend to discuss communication in the profession of software engineering. I will cover the relevant components of communication that a software engineer will encounter in all phases of software development. Topics include External Communications, Technical Communications, Project Communications, Research, Documentation, and Presentation. In each section, I will dive into details about the topics and strategies to master each type of communication.

Conference of engineers at Britannia Bridge. Oil painting by John Lucas. 1850

Definition

First, let’s give my quick definition of communication in general. Communication is the process to collect, organize, and transmit information. This may include two or more individuals such as client meetings, pair debugging sessions, and project meetings. One individual can also carry out communication such as research and documentation.

In the highly multidisciplinary software engineering field, communication may also involve individuals with varying degrees of technicality. From our definition and detailed explanation, we can see that communication in software engineering can be sophisticated due to the number of parties involved and the complexity of the SDLC (software development life cycle).

External Communications

This is the type of communication that involves any party that is outside of the organization. Typical parties may include the following:

  • Auditors
  • Regulators
  • Clients
  • Potential Customers
  • Investors
  • Shareholders
  • Society in large

The most important party among these is the client. The sole purpose of basically any software development is to serve the client in the best possible way. Next up are investors and shareholders. These individuals may be less demanding than the clients, but they are not to be overlooked as they provide the key ingredient, funding, to help a tech business thrive. Further down we have auditors and regulators. Not all software businesses will involve them, but software teams in Healthcare, Finance, and Public Sector often involve in these roles. For example, my Co-op company PHRI (Population Health Research Institute) involves a lot of auditing features on our product. Lastly, software teams or businesses often have to consider the societal impact.

These parties typically have varying degrees of technicality. I have discovered three rules that are common in software teams to facilitate external communications.

1. Establish clear models for communication.

Typical components in this model may include requirements elicitation meetings, progress report meetings, auditing meetings, as well as regular presentations.

2. Create new roles to facilitate clear communication.

For example, in my team at PHRI Co-op, we have BA (Business Analysts) dedicated to communicating with our clients — research teams — to define requirements and understand their concerns.

3. Clearly define and creatively explain technical terms and design

It is the team’s job to make technical information intuitive enough for the clients and other parties. A challenge for the team is to avoid losing or altering the meaning when applying a creative adaptation of the technical terms and design.

Technical Communications

This type of communication often exists between individuals at an expert level. Typical parties may include the following:

  • Testers
  • Developers (or Solution Developers)
  • Architects
  • Tech Leads
  • Staff Engineers
  • Product Managers

Technical communications typically involve development activities that require more expertise in the field including but not limited to the following:

  • Translating Requirements into Design
  • Communicating Bugs and Errors
  • Trouble Shooting
  • Discussing Solutions
  • Explaining Algorithms and Logic

The keys in technical communication, in my opinion, are accuracy, succinctness, and comprehensiveness. The three rules below describe in detail how to correctly communicate technical topics.

1. Be accurate with the information

It is important to be accurate about the error message, terminologies, and assumptions. Failure to present information accurately may result in misconception and may result in rework. Note that accuracy also applies to assumptions in that assumptions on error causes must be backed with sufficient evidence. When not enough evidence was present, developers can use their past experiences to make an assumption, but the following solution should be fault-tolerant.

2. Be succinct in the description

Concise descriptions can cause less confusions in technical communication as software engineering often include abstract concepts and processes. Usually what I do is eliminate any unnecessary adjectives and try to include only the verbs and nouns which often include terminologies. If the information cannot be simplified, try to structure it using bullet points or breaking it down into several smaller sub-topics. There is one trick about presenting a large volume of information — the MECE principle — which I will cover in the Presentation section.

3. Be comprehensive about the implications

Engineers often deal with real-world applications, which is why software engineers need to consider all the future implications to the system in terms of design. For example, when discussing a new architecture component or a new library, software engineers and architects often have to consider how the decisions will impact the interoperability, composability, and extensibility of the system. Developing maintainable systems often requires software engineers and architects to perform risk analysis and cost estimation on the system. Therefore, technical communication usually has to include extra information about the implications of the decisions.

Project Communications

This is a broad category that contains all the oral or written communications involved in a project. These communications serve two essential purposes — to document the project and to improve efficiency in SDLC (software development life cycle). I often like to refer to this type of communication as managerial communication with a tech flavor because a large part of this is about managing resources and operations in a team in a tech context.

Typical parties are similar to the technical communications.

Any communication related to projects will be relevant to each phase. Typical activities includes:

  • Goal Setting
  • Strategic Planning
  • Team Meeting
  • Status Reporting
  • Demonstration
  • Assessment
  • Logistics Communications

Project communications often include the whole team. Therefore, the speaker must be aware of the context and the scope. A very important aspect in project communication is to speak to the group, meaning that one has to consider the situation of different group members. Every project communication activity’s goal all boils down to a single purpose — to reach a consensus. Therefore, proper attitudes and methodologies must be applied to facilitate efficient project communications.

1. Provide enough background information

Oftentimes, even though people are working on the same team, information asymmetry can still occur as the application of the Division of Labor naturally separates different team member’s scope of work. The most straightforward way to provide background information is to explain it a bit more. Another is to link the topic to each member’s work and only address the relevant part.

2. Think about the overall goal

One of the main purposes of project communication is to assist the team to reach its overall goals. From my experiences, half of the project communication is devoted to defining the goals while the other half is contributed to achieve the goals. Therefore, it is important to define the goals correctly. Frameworks like OKR (Objectives and key results) and MBO (Management by objectives) help to facilitate the goal-setting process.

Ideally, after the goal has been defined, all the communications have to pertain to help the team achieve the goal. Team meetings and status reporting should reflect the current state in achieving the goals and the next steps to achieve the goal. The product manager is responsible for assessing the status of each goal and make further communications regarding delays to ensure the overall goal can be achieved eventually.

3. Keep track of the dependencies

This may sound like a good practice, but it is also important to facilitate effective project communications. Understand the dependencies between different modules can help one make more effective communication by eliminating repeated communications. For example, an issue related to data engineering can be addressed to both the data engineer and the developer so that no repeated communication will be made.

4. Develop a Body of Knowledge

A body of knowledge specific to the team will provide a guide to how to address certain issues or developing new features which will reduce the amount of time spent on researching. For example, in my Co-op placement in PHRI, we maintain a knowledgebase of clinical trials including the SOP workflows and auditing knowledge, which save the research time for developers.

Research

Research in software engineering can refer to two types of activities — formal academic research and nonscientific research.

Academic researches in software engineering refers to the process of using scientific investigation methods and analysis (math) to derive meaningful results. Research in software engineering is heavily based on discrete mathematics such as logic, probability, and statistics. I do not have the authority to speak to this type of communication as I haven’t engaged in any research activities.

Nonscientific researches are researches involved in the software engineering process including researching new tools, pioneering new solutions, and studying examples. This is a communication skill that every software engineer should possess to be successful in the industry. From my experiences, some activities includes:

  • Case study
  • Learning new tools
  • Pioneering solutions on forums (Stack overflow)
  • Exploring new designs and architectures
  • Market research

Most of these “research” activities are not formal at all and are meant to find solutions in a short amount of time. Of course, they can all be transformed into formal scientific researches if proper methods and tools are used. The goal of these quick searches is to generate meaningful outcomes in a short amount of time.

1. Define clear goals

Clear goals are always important whether you are browsing documentation, searching stack overflow, or reading blog articles. It’s easy to be carried away by other information. A good way to facilitate this is to clearly list and define your goals on a sticky note and constantly verify that the outcomes are relevant to the goal.

2. Take comprehensive notes

As mentioned above, listing the goals are only one step in taking good research notes. A good way to do this is to use an online document like Google docs to organize the notes into Goals, Links, Keywords, Assessments, Outcomes. This skill will be further explored in the Documentation section.

3. Conduct meaningful assessments

When exploring solutions to a bug or technical problems, one cannot omit assessments. I find it very helpful to divide your “research” into stages and do assessments at the end of each stage. A big problem software engineers face is that after hours of research, they find that the several solutions they arrived at are not helpful or relevant at all. Quantitatively divide the research into segments will help to modularize the research and minimize the risks.

4. Take necessary heuristics

Outcomes and efficiency are valued in any engineering discipline. Following the thoughts from the last strategy, taking heuristics in each stage will ensure overall success. A good way to take heuristics is to tailor the sample solution from your research to the context of the project. This could be a hacky solution, a test project, or a sample on the forum. Verification methods can be applied to check if the basic solution will yield the expected outcome.

Documentation

Documentation is crucial in any engineering discipline because they provide records for verification, assessments, and future planning. You may know that Upgrading and Revitalization are common in many traditional engineering disciplines like civil engineering. These efforts usually heavily rely on previous documentation. The same goes for Refactoring software engineering. Documentation about the design of the system is essential to help developers to figure out where and what to change.

Next, I will introduce some typical documentation types in software engineering.

Process Documentation

  • Problem Statement
  • Vision Statement
  • Initiation Document (PID)
  • Action plan document
  • Schedules
  • Status reports
  • Internal release document
  • Meeting notes
  • Working papers
  • Standards

System Documentation

  • Requirement document
  • System design and architecture document
  • UI & UX design document
  • QA document
  • Maintenance and help guide

Internal Technical Documentation

  • Source code document
  • Algorithms design document
  • API design document
  • Bugs and errors reports
  • Testing and validation reports
  • Testing standards

External Technical Documentation

  • Developer guides
  • API Specification
  • Best practices document
  • Learning resources
  • External release document

User Documentation

  • User manual
  • Administrator manual
  • Video tutorials
  • FAQs

In terms of its purpose in communication, documentation should aim for accurateness, succinctness, clearness, and comprehensiveness.

1. Accurateness: Check with credible sources

Accurateness in technical documentation can be achieved by thorough research from the internet. The most prominent way to ensure accurateness is to ask a specialist in the area to draft the document. It is also helpful to ask the specialist about technical details. Most importantly, the author must maintain a level of curiosity and rigorousness when writing.

2. Succinctness: Use shorter expressions

Succinctness can be maintained by using shorter and more straightforward sentences to communicate. Combined with structures like bullet points and ordered lists, shorter sentences serve as the basic elements of structured content that convey complex concepts.

3. Clearness: Develop structures

Structures help to transform complex concepts down into content that is easier to understand. It is important to pay attention to the structure or backbone of the content as they provide a way to organize information. When the reader approaches the documentation, he will first interpret the structure — the relationship — then dive into the details of the content.

4. Comprehensiveness: Cover all aspects of a tool

A framework or tool can sometimes have a lot of functionalities that one might never use, but since documentation aims towards different audiences that use the tool, it is crucial to explain everything well. One way to achieve this is to develop a framework of properties that most tools have, and check if anything is missed. For example, for a backend framework, one framework of properties can be — State management, Security, Event handling, Components, Architecture.

Presentation

Presentation is the combination of oral communication, body language, graphics, live demos, and other types of media, which requires high levels of creativity. When carefully designed and conducted, presentations can be a very powerful way to communicate ideas and outcomes in software engineering. A good presentation in the software engineering industry embodies the creativity, vision, plan, and hard work of the team.

Some typical presentation types in software engineering are listed below.

  • Pitch presentation
  • Proof of concept Demo
  • Requirement analysis presentation
  • Design presentation
  • Doman specific knowledge presentation
  • Project plan presentation
  • Project status reporting
  • Client review presentations
  • Product release Demo

Next, I will introduce some strategies to handle presentations in all types of presentations that will occur in the software engineering industry.

1. Research the audience and purpose

The two key components in any presentation are the audience and the purpose. Before any type of presentation, research has to be done regarding the audience’s overall technicality and role in the project. After this preliminary research is done, the purpose should be established to guide the style of the presentation and the information. The style of the presentation refers to how the information is presented, which may impact the body language, structure of the information, graphics, and impact. The information of a presentation may be more towards explaining the technical details, or more geared towards showing the vision and potential.

2. Carefully design and structure the presentation

The structure of the presentation varies based on its audience and setting. A more technical presentation may incorporate a more rigid structure aiming for a good understanding of the topic. A pitch presentation may utilize a more rigorous structure showing the potential and vision of the product. A design presentation may harness a progressive structure to demonstrate the insights into the product.

Order is another important aspect of the structure. Ordering the information in a certain way may generate some interesting ideas and insights into the product. A pitch presentation may start with the problem, then dive into some innovative design, and close with the vision to create an impact on investors. A design presentation between engineers could start with the technical aspect of the product and progress into the vision to ensure that the vision is derived from the technology itself. A client review presentation may start with the goal or vision, then evaluate the product, and close with the goals for the next cycle to verify that the features have met their purpose.

3. Be Adaptable towards the audience and settings

Software engineers have to deal with many different types of people in many different professional settings. A good way to deal with this is to make your presentation configurable, meaning that changes will be easy to make to adapt to a different audience and setting. One good way to facilitate this is to modularize the presentation so they can be quickly assembled for different circumstances.

In this case, special attention should be paid to the transitions between different modules. Develop well-connected presentations sometimes requires talent, but for most cases, it’s preparation and experiences. A good way to develop transition is to find commonalities between two modules and put emphasis on those sections.

Former Solutions Developer @PHRI