Table of contents<\/h3>\n\n\n- \nTable of contents<\/a><\/li>
- \nTechnical writing is everywhere<\/a><\/li>
- \nWhat is good grammar?<\/a><\/li>
- \nWriting code comments<\/a><\/li>
- \nWriting pull requests <\/a><\/li>
- \nReporting bugs<\/a><\/li>
- \nCommunicating with clients<\/a><\/li>
- \nWriting microcopy<\/a><\/li>
- \nWriting accessible markup<\/a><\/li>
- \nConclusion<\/a><\/li>
- \nTechnical writing resources<\/a><\/li><\/ul><\/div><\/div>\n\n\n
Technical writing is everywhere<\/h3>\n\n\n
Last year, the team behind the popular Mac Git client, Tower, polled more than 4,000 developers<\/a> and found that nearly 50% of them spent between 3-6 hours a day writing code.<\/p>\n\n\n\n![\"Bar](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2022\/06\/Screen-Shot-2022-05-13-at-7.51.37-AM.png?resize=1600%2C763&ssl=1\")
<\/figure>\n\n\n\nAnd yes, that’s one survey polling a pretty niche group, but I imagine many of us fall somewhere in that range. Whatever the case, a developer isn\u2019t writing code 24\/7, because as this poll suggests, we\u2019re spending plenty of time doing other things.<\/p>\n\n\n\n
That might include:<\/p>\n\n\n\n
- demoing a new feature,<\/li>
- documenting that new feature,<\/li>
- updating a work ticket related to that new feature, or<\/li>
- backlogging work to support that new feature.<\/li><\/ul>\n\n\n\n
Of course, there’s always time for bathroom breaks and Wordle too.<\/p>\n\n\n\n
Anyway, most of the things we typically do involve communicating with people like your team, colleagues, clients, users, and other developers.<\/p>\n\n\n\n
So we do spend a good chunk of our time communicating with humans through words<\/em> in addition to the communication we have with computers through code<\/em>. Words are written language. And if we wrote our words better, we\u2019d communicate better. When we communicate better, we\u2019re more likely to get what we want.<\/p>\n\n\n\nThat\u2019s Technical Writing 101.<\/p>\n\n\n\n![\"Venn](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2022\/06\/Slide-16_9-1-1-1.png?resize=1600%2C900&ssl=1\")
<\/figure>\n\n\n\nAnd it doesn\u2019t even end here.. Some programmers also like to make their own products, which means they need to make marketing part of their job. Technical writing plays a huge role in that too. So, yeah. I think it\u2019s pretty fair to say that technical writing is indeed<\/em> everywhere.<\/p>\n\n\nWhat is good grammar?<\/h3>\n\n\n
With so many programming languages out there, the last thing we want is to learn another one.<\/p>\n\n\n\n
Grammar<\/dfn> is an integral part of English, and it unlocks the full potential of communication. It makes us more formal, professional, and coherent.<\/p>\n\n\n\nLet me give you a quick rundown on language.<\/p>\n\n\n
The English syntax<\/h4>\n\n\n
Just like programming languages, English has a well-defined syntax, and it starts with words.<\/p>\n\n\n\n
Words are the building blocks of English, and they fall into eight buckets:<\/p>\n\n\n\n![\"Color](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2022\/06\/sentence-structure.jpg?resize=1130%2C138&ssl=1\")
<\/figure>\n\n\n\n\n\nNouns<\/h5>\n\n\n
These can be names of people, animals, places, concepts, and objects.
<\/p>\n\n\n\n
Example<\/strong>:
CSS<\/em> is one of the core languages of front-end development.<\/p>\n<\/div><\/div>\n<\/div>\n\n\n\n\nVerbs<\/h5>\n\n\n
Verbs convey action. Even “is” can be considered an action.<\/p>\n\n\n\n
Example:<\/strong>
Marcia codes<\/em> in the morning and answers<\/em> emails in the afternoon.<\/p>\n<\/div><\/div>\n<\/div>\n<\/div>\n\n\n\n\n\nAdjectives<\/h5>\n\n\n
Adjectives are how we describe nouns. They’re like meta that adds more detail to a sentence to paint a vivid picture.<\/p>\n\n\n\n
Examples:<\/strong><\/p>\n\n\n\n- CSS is an elegant<\/em> and poetic<\/em> language.<\/li>
- The HTML for tables is complex<\/em> and cumbersome<\/em>.<\/li>
- The Box Model is important<\/em> to understand CSS.<\/li><\/ul>\n<\/div><\/div>\n<\/div>\n\n\n\n\n
Prepositions<\/h5>\n\n\n
Prepositions create a relationship between a noun and other words, often indicating direction, time, location, and space.<\/p>\n\n\n\n
Examples:<\/strong><\/p>\n\n\n\n- Did you commit your work to<\/em> the repo?<\/li>
- What is the best approach for<\/em> this component?<\/li>
- We conducted interviews with<\/em> real users.<\/li><\/ul>\n<\/div><\/div>\n<\/div>\n<\/div>\n\n\n\n\n\n
Adverbs<\/h5>\n\n\n
Sometimes actions need to be more specific, so we use adverbs such as \u201cruns fast<\/em>\u201d and \u201ccompiles slowly<\/em>.\u201d They often end in “-ly.”<\/p>\n\n\n\nExamples:<\/strong><\/p>\n\n\n\n- This is easily<\/em> the best idea of them all.<\/li>
- Chip waited patiently<\/em> for Dale’s feedback.<\/li>
- The team worked diligently<\/em> on the project.<\/li><\/ul>\n<\/div><\/div>\n<\/div>\n\n\n\n\n
Conjunctions<\/h5>\n\n\n
Conjunctions connect phrases in a sentence. Remember this classic song<\/a> from the show School House Rocks<\/em>?<\/p>\n\n\n\nExamples:<\/strong><\/p>\n\n\n\n- CSS for styling while<\/em> HTML is for markup.<\/li>
- Yes, I write code, but <\/em>I also work on design.<\/li>
- That fixes the bug. Yet<\/em> it introduced a new one.<\/li><\/ul>\n<\/div><\/div>\n<\/div>\n<\/div>\n\n\n\n\n\n
Transitions<\/h5>\n\n\n
Paragraphs are made of sentences that are connected to each other using transitions.<\/p>\n\n\n\n
Examples:<\/strong><\/p>\n\n\n\n- There are many programming languages. However<\/em>, only a few are used in the web industry.<\/li>
- First<\/em>, clone the directory.<\/li>
- I like this approach but on the other hand<\/em>, I know another one.<\/li><\/ul>\n<\/div><\/div>\n<\/div>\n\n\n\n\n
Pronouns<\/h5>\n\n\n
When nouns become repetitive, we replace them with pronouns such as: \u201che,” \u201cit,” and \u201cthat.\u201d<\/p>\n\n\n\n
Examples:<\/strong><\/p>\n\n\n\n- CSS is a stylesheet language. We use it<\/em> to style websites.<\/li>
- Tony loves to code and he<\/em> practices every day.<\/li>
- Our customers are tech-savvy because they<\/em> know code.<\/li><\/ul>\n<\/div><\/div>\n<\/div>\n<\/div>\n\n\n\n
Think of these like UI<\/abbr> components: they are modular pieces you can move around to construct a complete and robust sentence, the same way you might piece together a complete and robust UI<\/abbr>. Do all of the components need to be there all of the time? Certainly not! Assemble a sentence with the pieces you need to complete the experience, just as you would with an interface.<\/p>\n\n\nVoice and tone<\/h4>\n\n\n
Vocabulary, punctuation, sentence structure, and word choice. These are all the ingredients of English. We use them to share ideas, communicate with our friends and family, and send emails to our coworkers.<\/p>\n\n\n\n
But it’s crucial to consider the sound<\/em> of our messages. It’s amazing how one exclamation point can completely shift the tone of a message:<\/p>\n\n\n\n- I like programming.<\/li>
- I like<\/em> programming! :)<\/li><\/ol>\n\n\n\n
It’s easy to confuse voice for tone, and vice versa.<\/p>\n\n\n\n
Voice<\/strong><\/dfn> is what concerns our choice of words, which depends on context. For example, a tutorial for beginners is more likely to use slang and informal language to convey a friendly voice, whereas documentation might be written in a formal, serious, and professional manner in an effort to get straight to the point.<\/p>\n\n\n\nThe same message, written in two different voices:<\/p>\n\n\n\n
- Fun: <\/strong>\u201cExpand your social network and stay updated on what\u2019s trending now.\u201d<\/li>
- Serious: <\/strong>\u201cFind jobs on one of the largest social networking apps and online jobs market.\u201d<\/li><\/ul>\n\n\n\n
It’s not unusual to accidentally write messages that come across as condescending, offensive, and unprofessional. This is where tone<\/dfn><\/strong> comes into play. Read your messages out loud<\/a>, get other people to read them for you, and experiment with your punctuation and sentence structure. That’s how you hone your tone.<\/p>\n\n\n\nHere’s another way to think of it: your voice never changes, but your tone does. Your voice is akin to who you are as a person, whereas tone is how you respond in a given situation.<\/p>\n\n\n
Active and passive voice<\/h4>\n\n\n
A sentence always contains an actor, a verb, and a target. The order in which these come determines if the sentence is written in an active or passive voice.<\/p>\n\n\n\n
The actor comes first in an active voice<\/dfn><\/strong>. For example: \u201cCSS paints the background.\u201d<\/p>\n\n\n\nSentences that use an active voice are more straightforward than their counterparts. They’re clearer, shorter, and more understandable \u2014 perfect for a more professional voice that gets straight to the point.<\/p>\n\n\n\n
With a passive voice<\/dfn><\/strong>, the actor comes last. (See what I did there?) That means our actor \u2014 CSS in this case \u2014 comes at the end like this: \u201cThe background is painted by CSS.\u201d<\/p>\n\n\n\nReaders usually convert a passive voice to an active voice in their heads, resulting in more processing time. If you’ve ever heard that writing in an active voice is better, this is usually the reason why. Tech writers prefer the active voice most of the time, with very few exceptions such as citing research: \u201cIt has been suggested that \u2026\u201d<\/p>\n\n\n\n
But that doesn’t mean you should always strive for an active voice. Switching from one to the other \u2014 even in the same paragraph \u2014 can make your content flow more seamlessly from one sentence to another if used effectively.<\/p>\n\n\n
Avoiding mistakes<\/h4>\n\n\n
Grammar is all about the structure and correctness of language, and there’s nothing better to achieve that than a quick proofreading of your document. It’s very important to rid your writings of spelling mistakes, grammar issues, and semantic imperfections.<\/p>\n\n\n\n
At the end of this article, I’ll show you the invaluable tools that professionals use to avoid writing mistakes. Obviously, there are built-in spell checkers in just about everything these days; our code editors even have spell-checking and linting plugins to help prevent mistakes. <\/p>\n\n\n\n
But if you’re looking for a one-stop tool for all-things grammar, Grammarly<\/a> is one of the most widely-used tools. I’m not getting a kickback for that or anything. It’s just a really great tool that many editors and writers use to write clean and clear content \u2014 similar to how you might use Emmet, eslint, or any other linter to write clean and clear code.<\/p>\n\n\nWriting code comments<\/h3>\n\n\n
The things we write for other developers can have a big impact on the overall quality of our work, whether it’s what we write in the code, how we explain the code, or how we give feedback on a piece of code.<\/p>\n\n\n\n
It\u2019s interesting that every programming language comes with a standard set of features to write a comment. They should explain what the code is doing. By that, I don\u2019t mean vague comments like this:<\/p>\n\n\n\n
red *= 1.2 \/\/ Multiply `red` by 1.2 and re-assign it<\/code><\/pre>\n\n\n\nInstead, use comments that provide more information:<\/p>\n\n\n\n
red *= 1.2 \/\/ Apply a 'reddish' effect to the image<\/code><\/pre>\n\n\n\nIt\u2019s all about context. \u201cWhat kind of program am I building?\u201d is exactly the kind of question you should be asking yourself.<\/p>\n\n\n
Comments should add value<\/h4>\n\n\n
Before we look at what makes a “good” code comment, here are two examples of lazy comments:<\/p>\n\n\n\n
const age = 32 \/\/ Initialize `age` to 32<\/code><\/pre>\n\n\n\nfilter: blur(32px); \/* Create a blur effect with a 32px radius *\/<\/code><\/pre>\n\n\n\nRemember that the purpose of a comment is to add value to a piece of code, not to repeat it. If you can\u2019t do that, you\u2019re better off just leaving the code as-is. What makes these examples “lazy” is that they merely restate what the code is obviously doing. In this case, the comments are redundant because they tell us what we already know \u2014 they aren’t adding value!<\/p>\n\n\n
Comments should reflect the current code<\/h4>\n\n\n
Out-of-date comments are no rare sight in large projects; dare I say in most<\/em> projects.<\/p>\n\n\n\nLet\u2019s imagine David, a programmer and an all-around cool guy to hang out with. David wants to sort a list of strings alphabetically from A to Z, so he does the obvious in JavaScript:<\/p>\n\n\n\n
cities = sortWords(cities) \/\/ sort cities from A to Z<\/code><\/pre>\n\n\n\nDavid then realizes that sortWords() actually sorts lists from Z to A. That\u2019s not a problem, as he can simply reverse the output:<\/p>\n\n\n\n
cities = sortWords(cities) \/\/ sort cities from A to Z\ncities = reverse(cities)<\/code><\/pre>\n\n\n\nUnfortunately, David didn\u2019t update his code comment.<\/p>\n\n\n\n
Now imagine that I didn\u2019t tell you this story, and all you saw was the code above. You\u2019d naturally think that after running that second line of code, `cities` would be sorted from Z to A! This whole confusion fiasco was caused by a stale comment.<\/p>\n\n\n\n
While this might be an exaggerated example, something similar can (and often does) happen if you\u2019re racing against a close deadline. Thankfully, this can be prevented by following one simple rule\u2026 change your comments the same time you change the code.<\/strong><\/p>\n\n\n\nThat\u2019s one simple rule that will save you and your team from a lot of technical debt<\/a>.<\/p>\n\n\n\nNow that we know what poorly written comments look like, let’s look at some good examples.<\/p>\n\n\n
Comments should explain unidiomatic code<\/h4>\n\n\n
Sometimes, the natural<\/em> way of doing things isn\u2019t right. Programmers might have to \u201cbreak\u201d the standards a bit, but when they do, it\u2019s advisable to leave a little comment explaining their rationale:<\/p>\n\n\n\n\u00a0function addSetEntry(set, value) {\u00a0\u00a0\u00a0\u00a0\n\u00a0\u00a0\/* Don't return `set.add` because it's not chainable in IE 11. *\/\u00a0\u00a0\n\u00a0\u00a0set.add(value);\n\u00a0\u00a0return set;\n}<\/code><\/pre>\n\n\n\nThat’s helpful, right? If you were responsible for reviewing this code, you may have been tempted to correct it without that comment there explaining what’s up.<\/p>\n\n\n
Comments can identify future tasks<\/h4>\n\n\n
Another useful thing to do with comments is to admit that there\u2019s more work to be done.<\/p>\n\n\n\n
\/\/ TODO: use a more efficient algorithm\nlinearSort(ids)<\/code><\/pre>\n\n\n\nThis way, you can stay focused on your flow. And at a later date, you (or someone else) can come back and fix it.<\/p>\n\n\n
Comments can link back to the source<\/h4>\n\n\n
So, you just found a solution to your problem on StackOverflow. After copy-pasting that code, it\u2019s sometimes a good thing to keep a link to the answer that helped you out so you can come back to it for future reference.<\/p>\n\n\n\n![\"Screenshot](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2022\/06\/stackoverflow-answer-link.png?resize=705%2C318&ssl=1\")
<\/figure>\n\n\n\n\/\/ Adds handling for legacy browsers\n\/\/ https:\/\/stackoverflow.com\/a\/XXXXXXX<\/code><\/pre>\n\n\n\nThis is important because solutions can change. It\u2019s always good to know where your code came from in case it ever breaks.<\/p>\n\n\n
Writing pull requests <\/h3>\n\n\n
Pull requests<\/dfn><\/strong> (PR<\/abbr>s) are a fundamental aspect of any project. They sit at the heart of code reviews. And code reviews can quickly become a bottleneck in your team\u2019s performance without good wording.<\/p>\n\n\n\nA good PR<\/abbr> description summarizes what<\/em> change is being made and why<\/em> it\u2019s being made. Large projects have a pull request template, like this one adapted from a real example<\/a>:<\/p>\n\n\n\n## Proposed changes\nDescribe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.\n\n## Types of changes\nWhat types of changes does your code introduce to Appium?\n - [ ] Bugfix (non-breaking change which fixes an issue)\n - [ ] New feature (non-breaking change which adds functionality)\n - ...\n\n## Checklist\n - [ ] I have read the CONTRIBUTING doc\n - [ ] I have signed the CLA\n - [ ] Lint and unit tests pass locally with my changes\n\n## Further comments\nIf this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc\u2026<\/code><\/pre>\n\n\nAvoid vague PR<\/abbr> titles<\/h4>\n\n\nPlease avoid titles that look like this:<\/p>\n\n\n\n
- Fix build.<\/li>
- Fix bug.<\/li>
- Add patch.<\/li><\/ul>\n\n\n\n
These don\u2019t even attempt<\/em> to describe what build, bug, or patch it is we’re dealing with. A little extra detail on what part of the build was fixed, which bug was squashed, or what patch was added can go a long way to establishing better communication and collaboration with your colleagues. It level-sets and gets folks on the same page.<\/p>\n\n\n\nPR<\/abbr> titles are traditionally written in imperative tense<\/a>. They\u2019re a one-line summary of the entire PR<\/abbr>, and they should describe what<\/em> is being done by the PR<\/abbr>.<\/p>\n\n\n\nHere are some good examples:<\/p>\n\n\n\n
- Support custom srcset attributes in NgOptimizedImage<\/li>
- Default image config to 75% image quality<\/li>
- Add explicit selectors for all built-in ControlValueAccessors<\/li><\/ul>\n\n\n
Avoid long PR<\/abbr>s<\/h4>\n\n\nA large PR<\/abbr> means a huge description, and no one wants to review hundreds or thousands of lines of code, sometimes just to end-up dismissing the whole thing!<\/p>\n\n\n\nInstead, you could:<\/p>\n\n\n\n
- communicate with your team through Issues<\/a>,<\/li>
- make a plan,<\/li>
- break down the problem into smaller pieces, or<\/li>
- work on each piece separately with its own PR<\/abbr>.<\/li><\/ul>\n\n\n\n
Isn\u2019t it much cleaner now?<\/p>\n\n\n
Provide details in the PR<\/abbr> body<\/h4>\n\n\nUnlike the PR<\/abbr> title, the body is the<\/em> place for all the details, including:<\/p>\n\n\n\n- Why is the PR<\/abbr> being done?<\/li>
- Why is this the best approach?<\/li>
- Any shortcomings to the approach, and ideas to solve them if possible<\/li>
- The bug or ticket number, benchmark results, etc.<\/li><\/ul>\n\n\n
Reporting bugs<\/h3>\n\n\n
Bug reports are one of the most important aspects of any project. And all great projects are built on user feedback. Usually, even after countless tests, it\u2019s the users that find most bugs. Users are also great idealists, and sometimes they have feature ideas; please listen to them!<\/p>\n\n\n\n
For technical projects, all of this stuff is done by reporting issues. A well-written issue is easy for another developer to find and respond to.<\/p>\n\n\n\n
For example, most big projects come with a template<\/a>:<\/p>\n\n\n\n <!-- Modified from angular-translate\/angular-translate -->\n ### Subject of the issue\n Describe your issue here.\n\n ### Your environment\n * version of angular-translate\n * version of angular\n * which browser and its version\n\n ### Steps to reproduce\n Tell us how to reproduce this issue.\n\n ### Expected behavior\n Tell us what should happen.\n\n ### Actual behavior\n Tell us what happens instead.<\/code><\/pre>\n\n\nGather screenshots<\/h4>\n\n\n
Capture the issue using your system\u2019s screen-shooting utility<\/a>.<\/p>\n\n\n\nIf it\u2019s a screenshot of a CLI<\/abbr> program, make sure that the text is clear. If it\u2019s a UI<\/abbr> program, make sure the screenshot captures the right elements and states.<\/p>\n\n\n\n
Technical writing is everywhere<\/h3>\n\n\n
Last year, the team behind the popular Mac Git client, Tower, polled more than 4,000 developers<\/a> and found that nearly 50% of them spent between 3-6 hours a day writing code.<\/p>\n\n\n\n And yes, that’s one survey polling a pretty niche group, but I imagine many of us fall somewhere in that range. Whatever the case, a developer isn\u2019t writing code 24\/7, because as this poll suggests, we\u2019re spending plenty of time doing other things.<\/p>\n\n\n\n That might include:<\/p>\n\n\n\n Of course, there’s always time for bathroom breaks and Wordle too.<\/p>\n\n\n\n Anyway, most of the things we typically do involve communicating with people like your team, colleagues, clients, users, and other developers.<\/p>\n\n\n\n So we do spend a good chunk of our time communicating with humans through words<\/em> in addition to the communication we have with computers through code<\/em>. Words are written language. And if we wrote our words better, we\u2019d communicate better. When we communicate better, we\u2019re more likely to get what we want.<\/p>\n\n\n\n That\u2019s Technical Writing 101.<\/p>\n\n\n\n And it doesn\u2019t even end here.. Some programmers also like to make their own products, which means they need to make marketing part of their job. Technical writing plays a huge role in that too. So, yeah. I think it\u2019s pretty fair to say that technical writing is indeed<\/em> everywhere.<\/p>\n\n\n With so many programming languages out there, the last thing we want is to learn another one.<\/p>\n\n\n\n Grammar<\/dfn> is an integral part of English, and it unlocks the full potential of communication. It makes us more formal, professional, and coherent.<\/p>\n\n\n\n Let me give you a quick rundown on language.<\/p>\n\n\n Just like programming languages, English has a well-defined syntax, and it starts with words.<\/p>\n\n\n\n Words are the building blocks of English, and they fall into eight buckets:<\/p>\n\n\n\n These can be names of people, animals, places, concepts, and objects. Example<\/strong>: Verbs convey action. Even “is” can be considered an action.<\/p>\n\n\n\n Example:<\/strong> Adjectives are how we describe nouns. They’re like meta that adds more detail to a sentence to paint a vivid picture.<\/p>\n\n\n\n Examples:<\/strong><\/p>\n\n\n\n Prepositions create a relationship between a noun and other words, often indicating direction, time, location, and space.<\/p>\n\n\n\n Examples:<\/strong><\/p>\n\n\n\n Sometimes actions need to be more specific, so we use adverbs such as \u201cruns fast<\/em>\u201d and \u201ccompiles slowly<\/em>.\u201d They often end in “-ly.”<\/p>\n\n\n\n Examples:<\/strong><\/p>\n\n\n\n Conjunctions connect phrases in a sentence. Remember this classic song<\/a> from the show School House Rocks<\/em>?<\/p>\n\n\n\n Examples:<\/strong><\/p>\n\n\n\n Paragraphs are made of sentences that are connected to each other using transitions.<\/p>\n\n\n\n Examples:<\/strong><\/p>\n\n\n\n When nouns become repetitive, we replace them with pronouns such as: \u201che,” \u201cit,” and \u201cthat.\u201d<\/p>\n\n\n\n Examples:<\/strong><\/p>\n\n\n\n Think of these like UI<\/abbr> components: they are modular pieces you can move around to construct a complete and robust sentence, the same way you might piece together a complete and robust UI<\/abbr>. Do all of the components need to be there all of the time? Certainly not! Assemble a sentence with the pieces you need to complete the experience, just as you would with an interface.<\/p>\n\n\n Vocabulary, punctuation, sentence structure, and word choice. These are all the ingredients of English. We use them to share ideas, communicate with our friends and family, and send emails to our coworkers.<\/p>\n\n\n\n But it’s crucial to consider the sound<\/em> of our messages. It’s amazing how one exclamation point can completely shift the tone of a message:<\/p>\n\n\n\n It’s easy to confuse voice for tone, and vice versa.<\/p>\n\n\n\n Voice<\/strong><\/dfn> is what concerns our choice of words, which depends on context. For example, a tutorial for beginners is more likely to use slang and informal language to convey a friendly voice, whereas documentation might be written in a formal, serious, and professional manner in an effort to get straight to the point.<\/p>\n\n\n\n The same message, written in two different voices:<\/p>\n\n\n\n It’s not unusual to accidentally write messages that come across as condescending, offensive, and unprofessional. This is where tone<\/dfn><\/strong> comes into play. Read your messages out loud<\/a>, get other people to read them for you, and experiment with your punctuation and sentence structure. That’s how you hone your tone.<\/p>\n\n\n\n Here’s another way to think of it: your voice never changes, but your tone does. Your voice is akin to who you are as a person, whereas tone is how you respond in a given situation.<\/p>\n\n\n A sentence always contains an actor, a verb, and a target. The order in which these come determines if the sentence is written in an active or passive voice.<\/p>\n\n\n\n The actor comes first in an active voice<\/dfn><\/strong>. For example: \u201cCSS paints the background.\u201d<\/p>\n\n\n\n Sentences that use an active voice are more straightforward than their counterparts. They’re clearer, shorter, and more understandable \u2014 perfect for a more professional voice that gets straight to the point.<\/p>\n\n\n\n With a passive voice<\/dfn><\/strong>, the actor comes last. (See what I did there?) That means our actor \u2014 CSS in this case \u2014 comes at the end like this: \u201cThe background is painted by CSS.\u201d<\/p>\n\n\n\n Readers usually convert a passive voice to an active voice in their heads, resulting in more processing time. If you’ve ever heard that writing in an active voice is better, this is usually the reason why. Tech writers prefer the active voice most of the time, with very few exceptions such as citing research: \u201cIt has been suggested that \u2026\u201d<\/p>\n\n\n\n But that doesn’t mean you should always strive for an active voice. Switching from one to the other \u2014 even in the same paragraph \u2014 can make your content flow more seamlessly from one sentence to another if used effectively.<\/p>\n\n\n Grammar is all about the structure and correctness of language, and there’s nothing better to achieve that than a quick proofreading of your document. It’s very important to rid your writings of spelling mistakes, grammar issues, and semantic imperfections.<\/p>\n\n\n\n At the end of this article, I’ll show you the invaluable tools that professionals use to avoid writing mistakes. Obviously, there are built-in spell checkers in just about everything these days; our code editors even have spell-checking and linting plugins to help prevent mistakes. <\/p>\n\n\n\n But if you’re looking for a one-stop tool for all-things grammar, Grammarly<\/a> is one of the most widely-used tools. I’m not getting a kickback for that or anything. It’s just a really great tool that many editors and writers use to write clean and clear content \u2014 similar to how you might use Emmet, eslint, or any other linter to write clean and clear code.<\/p>\n\n\n The things we write for other developers can have a big impact on the overall quality of our work, whether it’s what we write in the code, how we explain the code, or how we give feedback on a piece of code.<\/p>\n\n\n\n It\u2019s interesting that every programming language comes with a standard set of features to write a comment. They should explain what the code is doing. By that, I don\u2019t mean vague comments like this:<\/p>\n\n\n\n Instead, use comments that provide more information:<\/p>\n\n\n\n It\u2019s all about context. \u201cWhat kind of program am I building?\u201d is exactly the kind of question you should be asking yourself.<\/p>\n\n\n Before we look at what makes a “good” code comment, here are two examples of lazy comments:<\/p>\n\n\n\n Remember that the purpose of a comment is to add value to a piece of code, not to repeat it. If you can\u2019t do that, you\u2019re better off just leaving the code as-is. What makes these examples “lazy” is that they merely restate what the code is obviously doing. In this case, the comments are redundant because they tell us what we already know \u2014 they aren’t adding value!<\/p>\n\n\n Out-of-date comments are no rare sight in large projects; dare I say in most<\/em> projects.<\/p>\n\n\n\n Let\u2019s imagine David, a programmer and an all-around cool guy to hang out with. David wants to sort a list of strings alphabetically from A to Z, so he does the obvious in JavaScript:<\/p>\n\n\n\n David then realizes that sortWords() actually sorts lists from Z to A. That\u2019s not a problem, as he can simply reverse the output:<\/p>\n\n\n\n Unfortunately, David didn\u2019t update his code comment.<\/p>\n\n\n\n Now imagine that I didn\u2019t tell you this story, and all you saw was the code above. You\u2019d naturally think that after running that second line of code, `cities` would be sorted from Z to A! This whole confusion fiasco was caused by a stale comment.<\/p>\n\n\n\n While this might be an exaggerated example, something similar can (and often does) happen if you\u2019re racing against a close deadline. Thankfully, this can be prevented by following one simple rule\u2026 change your comments the same time you change the code.<\/strong><\/p>\n\n\n\n That\u2019s one simple rule that will save you and your team from a lot of technical debt<\/a>.<\/p>\n\n\n\n Now that we know what poorly written comments look like, let’s look at some good examples.<\/p>\n\n\n Sometimes, the natural<\/em> way of doing things isn\u2019t right. Programmers might have to \u201cbreak\u201d the standards a bit, but when they do, it\u2019s advisable to leave a little comment explaining their rationale:<\/p>\n\n\n\n That’s helpful, right? If you were responsible for reviewing this code, you may have been tempted to correct it without that comment there explaining what’s up.<\/p>\n\n\n Another useful thing to do with comments is to admit that there\u2019s more work to be done.<\/p>\n\n\n\n This way, you can stay focused on your flow. And at a later date, you (or someone else) can come back and fix it.<\/p>\n\n\n So, you just found a solution to your problem on StackOverflow. After copy-pasting that code, it\u2019s sometimes a good thing to keep a link to the answer that helped you out so you can come back to it for future reference.<\/p>\n\n\n\n This is important because solutions can change. It\u2019s always good to know where your code came from in case it ever breaks.<\/p>\n\n\n Pull requests<\/dfn><\/strong> (PR<\/abbr>s) are a fundamental aspect of any project. They sit at the heart of code reviews. And code reviews can quickly become a bottleneck in your team\u2019s performance without good wording.<\/p>\n\n\n\n A good PR<\/abbr> description summarizes what<\/em> change is being made and why<\/em> it\u2019s being made. Large projects have a pull request template, like this one adapted from a real example<\/a>:<\/p>\n\n\n\n Please avoid titles that look like this:<\/p>\n\n\n\n These don\u2019t even attempt<\/em> to describe what build, bug, or patch it is we’re dealing with. A little extra detail on what part of the build was fixed, which bug was squashed, or what patch was added can go a long way to establishing better communication and collaboration with your colleagues. It level-sets and gets folks on the same page.<\/p>\n\n\n\n PR<\/abbr> titles are traditionally written in imperative tense<\/a>. They\u2019re a one-line summary of the entire PR<\/abbr>, and they should describe what<\/em> is being done by the PR<\/abbr>.<\/p>\n\n\n\n Here are some good examples:<\/p>\n\n\n\n A large PR<\/abbr> means a huge description, and no one wants to review hundreds or thousands of lines of code, sometimes just to end-up dismissing the whole thing!<\/p>\n\n\n\n Instead, you could:<\/p>\n\n\n\n Isn\u2019t it much cleaner now?<\/p>\n\n\n Unlike the PR<\/abbr> title, the body is the<\/em> place for all the details, including:<\/p>\n\n\n\n Bug reports are one of the most important aspects of any project. And all great projects are built on user feedback. Usually, even after countless tests, it\u2019s the users that find most bugs. Users are also great idealists, and sometimes they have feature ideas; please listen to them!<\/p>\n\n\n\n For technical projects, all of this stuff is done by reporting issues. A well-written issue is easy for another developer to find and respond to.<\/p>\n\n\n\n For example, most big projects come with a template<\/a>:<\/p>\n\n\n\n Capture the issue using your system\u2019s screen-shooting utility<\/a>.<\/p>\n\n\n\n If it\u2019s a screenshot of a CLI<\/abbr> program, make sure that the text is clear. If it\u2019s a UI<\/abbr> program, make sure the screenshot captures the right elements and states.<\/p>\n\n\n\n<\/figure>\n\n\n\n<\/figure>\n\n\n\nWhat is good grammar?<\/h3>\n\n\n
The English syntax<\/h4>\n\n\n
<\/figure>\n\n\n\nNouns<\/h5>\n\n\n
<\/p>\n\n\n\n
CSS<\/em> is one of the core languages of front-end development.<\/p>\n<\/div><\/div>\n<\/div>\n\n\n\nVerbs<\/h5>\n\n\n
Marcia codes<\/em> in the morning and answers<\/em> emails in the afternoon.<\/p>\n<\/div><\/div>\n<\/div>\n<\/div>\n\n\n\nAdjectives<\/h5>\n\n\n
Prepositions<\/h5>\n\n\n
Adverbs<\/h5>\n\n\n
Conjunctions<\/h5>\n\n\n
Transitions<\/h5>\n\n\n
Pronouns<\/h5>\n\n\n
Voice and tone<\/h4>\n\n\n
Active and passive voice<\/h4>\n\n\n
Avoiding mistakes<\/h4>\n\n\n
Writing code comments<\/h3>\n\n\n
red *= 1.2 \/\/ Multiply `red` by 1.2 and re-assign it<\/code><\/pre>\n\n\n\nred *= 1.2 \/\/ Apply a 'reddish' effect to the image<\/code><\/pre>\n\n\n\nComments should add value<\/h4>\n\n\n
const age = 32 \/\/ Initialize `age` to 32<\/code><\/pre>\n\n\n\nfilter: blur(32px); \/* Create a blur effect with a 32px radius *\/<\/code><\/pre>\n\n\n\nComments should reflect the current code<\/h4>\n\n\n
cities = sortWords(cities) \/\/ sort cities from A to Z<\/code><\/pre>\n\n\n\ncities = sortWords(cities) \/\/ sort cities from A to Z\ncities = reverse(cities)<\/code><\/pre>\n\n\n\nComments should explain unidiomatic code<\/h4>\n\n\n
\u00a0function addSetEntry(set, value) {\u00a0\u00a0\u00a0\u00a0\n\u00a0\u00a0\/* Don't return `set.add` because it's not chainable in IE 11. *\/\u00a0\u00a0\n\u00a0\u00a0set.add(value);\n\u00a0\u00a0return set;\n}<\/code><\/pre>\n\n\n\nComments can identify future tasks<\/h4>\n\n\n
\/\/ TODO: use a more efficient algorithm\nlinearSort(ids)<\/code><\/pre>\n\n\n\nComments can link back to the source<\/h4>\n\n\n
<\/figure>\n\n\n\n\/\/ Adds handling for legacy browsers\n\/\/ https:\/\/stackoverflow.com\/a\/XXXXXXX<\/code><\/pre>\n\n\n\nWriting pull requests <\/h3>\n\n\n
## Proposed changes\nDescribe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.\n\n## Types of changes\nWhat types of changes does your code introduce to Appium?\n - [ ] Bugfix (non-breaking change which fixes an issue)\n - [ ] New feature (non-breaking change which adds functionality)\n - ...\n\n## Checklist\n - [ ] I have read the CONTRIBUTING doc\n - [ ] I have signed the CLA\n - [ ] Lint and unit tests pass locally with my changes\n\n## Further comments\nIf this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc\u2026<\/code><\/pre>\n\n\nAvoid vague PR<\/abbr> titles<\/h4>\n\n\n
Avoid long PR<\/abbr>s<\/h4>\n\n\n
Provide details in the PR<\/abbr> body<\/h4>\n\n\n
Reporting bugs<\/h3>\n\n\n
<!-- Modified from angular-translate\/angular-translate -->\n ### Subject of the issue\n Describe your issue here.\n\n ### Your environment\n * version of angular-translate\n * version of angular\n * which browser and its version\n\n ### Steps to reproduce\n Tell us how to reproduce this issue.\n\n ### Expected behavior\n Tell us what should happen.\n\n ### Actual behavior\n Tell us what happens instead.<\/code><\/pre>\n\n\nGather screenshots<\/h4>\n\n\n