Programmers need to learn how to communicate

Having something isn't enough; it's also about how you package it. Even if you have the best ideas, elegant code, and practical thoughts, if you can't communicate with others, they will never bear fruit. Without effective communication, good ideas become orphans.

As developers, we must communicate on multiple levels. We spend hours in meetings, listening and talking. We collaborate with end-users to understand their needs. We write code to convey our intent to machines; we write documentation to pass our thoughts to the next generation of developers. We write proposals and memos to explain resource requests, report statuses, and propose new solutions. We work within teams every day—advocating ideas, tweaking practices, or suggesting improvements. Most of our daily time is spent communicating, so we need to excel at it.

Treat English (or whatever your native language is) as another programming language. Write prose in natural language like you write code: respecting DRY principles, ETC, automation, and more.

（Soft Skills for Programmers：unstopable.gumroad.com/l/btxvm）

English is just another programming language.

Understand your audience.

Communication involves conveying information. To get the message across, you need to understand the audience's needs, interests, and abilities. We've all been in those meetings where a tech enthusiast rambles about the intricacies of a complex technology, leaving the marketing vice president with a glazed look. That's not communication, it's just talk, and it's annoying. Imagine you want to propose implementing a web-based system for end-users to submit error reports. Depending on your audience, you can describe the system in various ways. End-users might prefer 24/7 error report submission without waiting on the phone. The marketing department could use this feature to boost sales. Support managers might find it a reason to be happy—fewer employees needed as error reports can be automated. Finally, developers might be excited about gaining experience in web-based architecture or trying out a new database engine. By advocating effectively to each group, you can make them all excited about your project.

As with all forms of communication, the trick here is to gather feedback. Don't just wait for questions to arise; ask them. Pay attention to body language and facial expressions. Neuro-linguistic programming has a presupposition that "the meaning of communication is the response you get." In the process of communicating, continually improve your understanding of your audience.

Know what you want to say.

In more formal business communication, the hardest part might be figuring out what you actually want to say. Novelists often outline their books with numerous details from the start, but technical writers tend to sit at a keyboard and type:

1、Introduction.

2、Things that come to mind.

Plan what you want to say, create an outline, and ask yourself, "Am I conveying what I want to say to my audience in the right way?" Condense it until it's as concise as possible.

This approach is not limited to writing documents. When you're about to attend an important meeting or call a major client, jot down your thoughts and prepare multiple strategies to make your point understood.

Now that you know what your audience wants, it's time to plan how to deliver it.

Choose the timing.

It's Friday afternoon at 6 pm, the auditors have been around for a week, your boss's young son is in the hospital, and it's pouring rain outside, making your journey home a nightmare. This might not be the best time to ask her to upgrade your laptop's memory. One aspect of understanding your audience is figuring out their priorities. Catching a manager to discuss ideas about a code repository is more likely when they've just been reprimanded by their boss for losing some source code. What you say not only has to be relevant but also timely. Sometimes, all it takes is asking a simple question: "Is now a good time to discuss...?"

Choose the style.

Adjust your expression based on your audience. Some people want a formal "just the facts" brief. Others prefer a bit of small talk before diving into business. How skilled and experienced are they in this field? Are they experts or beginners? Do they need hand-holding or just a "TL;DR" version? If in doubt, ask.

However, remember that communication is a two-way street. If someone wants you to explain something in a few words, and you find that it can't be summarized in a couple of sentences, let them know. Feedback like this is also a form of communication.

Make it look good.

Ideas matter, but the audience also wants a good presentation.

Too many developers (including their managers) focus solely on content when writing documents. We disagree. Any cook (or host of a cooking show) will tell you that even something as simple as an unappetizing appearance can ruin the hours of hard work you put into cooking.

Today, there's no excuse for producing poorly formatted documents. Whether using Markdown or word processing software, modern tools can output beautifully formatted results. You only need to learn a few basic commands. If you're using word processing software, use its style sheets for consistency. (Your company should have prepared style sheets you can use directly.) Learn how to set headers and footers. Look at sample documents in the software package, study their style and layout. Turn on spell check, start by letting automatic checks fix spelling errors, then manually proofread. After all, some typos might escape automated checks.

Involve the audience.

Often, we find that the process of creating a document is more important than the final draft. Whenever possible, involve readers in the initial draft of a document. Listen to their feedback and tap into their wisdom. This helps build good working relationships, and through this process, better documents are produced.

Be a listener.

If you want others to listen to you, there's a skill you must master: listening to them. Even if you have all the information, even if you're standing in front of 20 well-dressed individuals in a formal meeting—if you don't listen to them, they won't listen to you.

Encourage people to talk by asking questions, and try to get them to summarize your points. Turn meetings into conversations to better convey your ideas. Who knows, you might even learn something.

Respond to others.

When you ask someone a question, if they don't answer, you consider them rude. So, when someone emails or sends you a memo asking for information, requesting something from you, how many times have you failed to respond? Busy days often lead to forgetting things. Always remember to reply to emails, even a simple "I'll get back to you later" will suffice. Inform others promptly—it makes it easier for people to forgive your occasional oversight and lets them know you haven't forgotten about them.

What you say and how you say it are equally important.

Unless you're completely isolated from the world, you must learn to communicate. The more effective your communication, the greater your influence.

Documentation.

Lastly, there's an issue of communication through documentation. Typically, developers don't invest too much effort into documentation; at best, they see it as an obligatory task, and at worst, they consider it a low-priority task—hopefully one that the project manager forgets about at the end of the project.

Practical programmers view documentation as an integral part of the entire development process. To make documentation easier, avoid redundant work and save time by keeping documentation readily available—write it directly in the code. In fact, all practical principles used for coding should also apply to documentation.

Embed documentation, don't just attach it.

Generating attractive documentation using comments in the source code is straightforward. It's recommended to add comments to modules and exported functions; this can greatly assist other developers who use them.

However, the practice of adding comments to every function, data structure, type declaration, etc., is questionable. Such mechanical commenting practices can actually make the code harder to maintain: changing something means updating two things. Therefore, non-API comments should be limited to discussing the reasons for their existence and their intent and purpose. When the code already demonstrates how things are done, comments become redundant—violating the DRY principle.
Commenting the source code presents a great opportunity to record project details that can't be documented elsewhere: engineering trade-offs, decisions rationale, rejected alternatives, etc.

Summary.

· Understand what you want to say.

· Understand your audience.

· Choose the right timing.

· Select an appropriate style.

· Make it visually appealing.

· Involve your audience.

· Be a good listener.

· Respond to others.

· Bind code and documentation together.

（Soft Skills for Programmers：unstopable.gumroad.com/l/btxvm）

Online communication.

Everything said about written communication applies to email, social media posts, blogs, etc. Email, especially, has become the primary means of communication within companies; it's used for contract discussions, dispute resolution, and even as evidence in court. However, for some reason, people hesitate to send a tattered piece of paper but don't mind sending seemingly disorganized and incoherent emails worldwide.

My advice is simple:

· Proofread before hitting send.

· Double-check spelling and catch possible auto-correct mistakes.

· Use a simple format. Not all email clients render like modern browsers; your beautifully formatted email might end up scrambled. Many website comments and replies don't allow HTML tags.

· Quote the original text sparingly. Nobody likes receiving a reply email with hundreds of lines of their own text, followed by just one line saying "I agree."

· If quoting someone's email, attribute it and do inline quoting (rather than putting it in an attachment). The same goes for quoting on social media platforms.

· Avoid insulting others online; don't be a troll unless you enjoy being trolled or getting flamed. If you wouldn't say certain things to someone's face, don't say them online either.

· Check the recipient list before sending. This is a well-worn caution—if you're criticizing your boss in a department email, be careful not to add your boss to the forwarding list. Of course, it's best not to criticize your boss in an email at all.

Emails and social media posts are irreversible once sent; numerous large companies and politicians have fallen into this trap. Therefore, treat emails just like any written memo or report.

（Soft Skills for Programmers：unstopable.gumroad.com/l/btxvm）