Recently I had the honor to lead the learning module at the Collab Lab’s weekly meeting, where we discussed and brainstormed the ways of effective written communication for developers.
The Collab Lab is a non-profit organization that exists to help early-career developers acquire practical experience to effectively work on software teams. Participants remotely collaborate to build real-world projects under the guidance of professional and experienced web developers.
As in real-world settings, communication at the Collab Lab is one of the key ingredients for successful work. This includes, verbally demonstrating new features of the production application, writing issues and user stories, peer reviews, and strong Pull Requests.
For the nature of the learning module, I will focus on the three important aspects of successful communication principles for developers. These are Documentation, Pull Requests, and Comments in Code. The blog will help you conceptualize Why these practices are important and How do we make them effective.
Documentation
As software engineers, most of us will agree that documentation is one of the most important pieces of information that helps us guide through the usage of a software or application that we intend to use. Equally, It is meant to translate technical mechanisms of the building process for non-technical folks. In a way, it is a record of the history that narrates the process of when, why, and how the development has been done.
Why?
Good documentation is crucial for making the product successful and at the same time improving the development process.
-‘What did I do again?’ -
As we write programs and websites, the codebase constantly grows and new building blocks are added on top of each other. As time goes by, it will be inevitable to not re-visit blocks of code we wrote in the past. You will all agree that most of the time it is very hard to remember what we did 6, 8, or even 12 months ago. This is where the beauty of documentation shines. It helps us recall our actions and trace them back. Similarly, documentation is a great tool for re-visiting big decisions and understand why we made certain choices over the others. Having this reference saves us a lot of time researching things that we’ve already explored.
Documentation is great for learning purposes. As we write things down it helps to remember your reasoning better. We might internalize thoughts well in our head, but as we structurally write a document, it assists with solidifying the concepts.
Documentation is remarkable for onboarding new team members. Documentation is a note not only for our future self but also for fellow developers. High level of explanation as to how the company works, where all the resources are located, what is the workflow, and how are they structured; Having this kind of document as a point of reference, makes team members self-sufficient and comfortable. A great example I can think of is the Orientation file by The Collab Lab. Starting from the overall mission and goal of the project, location for resources, project cadence and duration, weekly sync, coordination and communication, development process; Everything is documented in one place which makes the onboarding process super smooth.
Open and decentralized documentation avoids institutional knowledge. There should not be one person or group of people who possess more information than the others. What really makes organizations and teams healthy is the equal accessibility of knowledge and information. By documenting our work, we empower every team member to be true owners of the product, make the right decisions, and equally contribute to the overall goal.
Besides, a decentralized document of knowledge keeps companies work and function perfectly, even if someone is sick, unavailable, or is leaving a company.
How?
How do we make effective documentation and how to structure the course of action?
The right mindset to have when writing documentation is to think about a person who knows the least about the work you do. The style could vary from company to company. However, when it comes to the actual information, it should be easily digestible by the entire range of users and all levels of developers. In addition, to make documentation more effective, try to optimize for the person who needs a quick reference. Utilize as many formatting tools as possible, such as a table of content, good headings, sections, bulleted lists, hyperlinks to further knowledge, code blocks, and more. Graphical representation of information is tremendously helpful as well.
Pull Requests
As a Bootcamp graduate, I briefly encountered Pull Requests during my studies and it was very hard to understand the real power of it until I properly started using it.
For those who have not come across Pull Request yet, it is a feature that helps developers to propose their changes through a new branch and integrate them into one repository. PR is more than a feature. It is a form of documentation in a way, where teammates can discuss, give feedback and code reviews, collaborate, and “follow-up commits before your changes are merged into the base branch.”
Why?
The reasons why good Pull Requests are important is to optimize the development process and increase the efficiency of the teamwork.
A lot of times, fellow developers may not know what you have built and how you implemented new features. They may not know the user stories or what the acceptance criteria are. This is where Pull Requests’ power comes into play. Well documented PR gives reviewers context on your code and helps them get on the same page much faster. Additionally, a clear and comprehensive record of information is a guarantee for better feedback.
PRs are also an opportunity to teach others new things. Sharing and decentralizing knowledge is crucial when it comes to proposing changes into the project. Providing links that reference resources that assist you solve specific issues helps not only to grow as a team but also it is imperative for the reviewer to understand why you made certain decisions.
Being accustomed to writing a good Pull Request is so useful for junior developers who are in the process of finding their first or next job. It helps not only to remember your thought process but it is also a very strong indication of your reliable collaboration knowledge.
To conclude, Pull Request is another form of a solid communication tool on your development team.
How?
The way you can make PRs shine is to offer a visual representation of a new feature using screenshots, gifs, and videos. You will agree that sometimes “a picture is worth a thousand words.” Similarly, provide links around new concepts that can further teams knowledge.
Another great tip for good PRs is a self-review. This practice will help you provide better content, while also helping you conceptualize the uncertainty that you might have around your solution.
Comments in Code
Comments in code are another powerful tool for communication. Unlike, documentation which is an abstract form of your code, or Pull Requests that is a specific section of the codebase, - comments that live inside your code can bring very valuable information. While there might be teams that actively utilize this practice, there are others who don’t. I believe, if they are rightly used, comments could be a great instrument for assistance.
How?
While implementing comments in your code, a good way to conceive them is by asking why you did something, rather than what. The reasoning behind this is that well-written code usually is self-explanatory. Descriptive variable and function names, such as addItemToDatabase and getUTCNowInMilliSec provide a very clear description of their purpose. Therefore, it would be redundant to repeat their motive with comments.
To make it simple, a good example of a comment would be to write Why your teammate decided to convert current UTC in milliseconds.
In conclusion
Communication truly is a key to be successful in most of the aspects of the development process. It helps not only us to be better programmers, but also sets the whole team and ecosystem up for success. It empowers every developer and helps the industry to achieve bigger innovations.
All Credit goes to The Collab Lab for providing the knowledge and material for this blog!
Follow me on Twitter
For more blog posts visit my Medium Page
Top comments (0)