Jacquelyn Wheeler's Blog

As the world grapples with the coronavirus pandemic, a lot of people are suddenly finding themselves working from home and being told they should physically isolate from others. For most writers, this is a blessing (ahhhh, the quiet!), but for extroverts and people who haven't worked from home before, this can be downright scary.

Since I've worked from home for most of my career, I thought I'd share some tips for making the experience fun and rewarding.
Tip #1: Get dressedEven if you're not going to have any video meetings, put on an outfit that makes you feel like working. You don't have to go as far as wearing a suit and doing your full makeup routine if you don't want to, but getting out of your pajamas gives you a psychological boost and signals that it's time to work.
Tip #2: Schedule your dayOne of the biggest challenges of working from home is that people tend to lose a lot of the structure they find in the office. The lure of social media, laundry, pets, and the fridge can all eat into your productivity.

Schedule your day starting with the meetings you have to call in to, then carve out time slots for the projects you need to work on today, and then (and just as importantly) carve out time for breaks during which you take the dog for a walk, play with the cats, check in on Facebook, etc. Just make sure you schedule it in, and be sure to consult your schedule throughout the day, making adjustments as needed. I use the Self Journal and highly recommend it for planning your day.
Tip #3: Turn on video in your conference callsSeeing your colleagues' faces will help you feel much more connected and less isolated. Furthermore, communication flows more smoothly when you can see each others' faces, because you can pick up on cues when someone wants to jump in and you can see their reactions. If you have a slow internet connection, though, you might have to turn off video to keep the audio from dropping sporadically. In this case, if your meeting app allows you to have a photo of yourself, use a friendly photo that shows you smiling. Tip #4: Carve out a space just for workIf at all possible, try to set aside a space that is just for work and nothing else. If you only have a kitchen table, try to sit in one seat for working and another seat for eating. Or make the kitchen table your desk and eat while sitting on the sofa. (Wear earplugs or headphones while working if you're in a noisy environment.) It's very easy to have work and home life bleed into each other when you work from home, which can lead to lost productivity as well as burnout. Make sure your working hours are mostly work and your personal hours are mostly personal. By carving out a physical space that's just for work, it can help you better separate your work time from your personal time.  Tip #5: Plan social eventsWait, aren't we supposed to be practicing social distancing? Yes, but planning some remote social interaction can be critical for maintaining your mental health during isolation. 
Over this last weekend, I held an open mic night via Zoom. I created an event for it on Facebook and invited a bunch of people, and about a dozen called in. One person read a story they had written, and a couple of us performed songs. The rest of the time we just chatted and caught up as if we were at a cocktail party. 
Another friend did a live DJ set from his living room and streamed it over Facebook Live, and I had a blast dancing for over an hour while occasionally texting with other friends who had joined the live stream. And this week a friend and I are planning remote game nights; poker, Yahtzee, charades, bingo, and trivia contests are all good candidates.  
If this sounds like more social time than your introverted nature can bear, have a phone call with family or friends so you at least hear other voices. And also take a look at the virtual museum tours you can do online. Tip #6: ExerciseExercise is so important for your mental health. I am one of those rare people who has never experienced runner's high and actually feels worse right after exercise, but it's important for my overall health and sense of well-being. I'm a big fan of Peloton, especially because it provides such a strong community without having to leave the house. If you don't have the money or space for the bike or tread, no worries: the Peloton app, which is free for 30 days, has tons of great classes you can do without Peloton equipment. Tip #7: Spend time on creativity and learningThere's never been a better time to work on your novel, learn guitar, color in coloring books, create playlists of music, read that book you got for Christmas, write poetry, paint, or simply journal about your experiences during this time of isolation. Check out Master Classes, or just look up YouTube videos and learn how to do something new. When we use this time to create or learn something new, we feel even more productive, and that improves our sense of self-worth and accomplishment, which in turns boosts our mental health.
Tip #8: Cut way back on alcoholOne of the big risks with isolation is depression, and alcohol is a depressant. It also leads us toward slothing on the sofa and watching TV instead of exercising and being creative. And if you're sharing space with family or roommates during this time, drinking alcohol will increase your chances of getting on each other's nerves and triggering arguments. It's really important that we take excellent care of ourselves during this time, so do the things that promote your physical and mental health.
Tip #9: Help othersResearch has shown that helping others helps us feel better. There are many small ways we can do this while we're isolated. If you are healthy and know of someone who is in a high-risk group, offer to do their grocery shopping for them, but only if you can be extremely careful and mindful of hygiene. If you know someone who lives alone, call them and check in on them. If you know someone has lost their job, offer them financial assistance if you can. Buy gift certificates from your favorite restaurants so that they get money now to tide them over during this time, and you can go enjoy a meal in a few weeks.

Do you have other ideas for how to stay happy and productive while staying home? Pleas share them in the comments.

In my last post, I discussed the importance of writing and how it makes you smarter. But it's one thing to understand why you should be writing and a whole other matter to actually do it. If you've ever had trouble finishing (or starting!) a writing project, try these nine steps.
1. Start with what interests youDid you recently create a new feature? Hear about something cool you want to learn more about and share? Take time to research the topic, why it matters, and how it compares to similar features, products, or ideas.
2. Read similar contentIf you're going to write a blog, see what you like about other blogs. The same goes for  documentation. Pay attention to what you like and don't like, and most importantly, why.
3. Write your draftDon't worry about perfection! This is the time to get your ideas down. Part of what causes us to dread the blank page is fear of doing it wrong. There is no "wrong" in the draft stage. Just start writing.
4. Organize your contentNow that you've got your ideas down, look at the flow of the information. Are you starting with something that will hook the reader's interest or with something irrelevant or too detailed? Does the body of the document go off on tangents or add unrelated points in the middle of a paragraph? Are you summarizing at the end and giving further resources the reader can link to, or does it just trail off?
5. EditGo through each sentence and ask whether it adds value to the reader. Cut unnecessary words, phrases, and sentences. Make sure each sentence makes grammatical sense, and if you're unsure about a word or how to use commas correctly, look it up.
6. Take a break, and then read it againTime away helps your brain reset so you can spot those gaps I mentioned in my last post.
7. Get it reviewedThis is the most important step. Send your draft to people who can give you feedback on the subject matter, the writing, or both. Wait for all the feedback to come in, and then (politely!) ask for clarification on unclear feedback. If you get conflicting feedback from different reviewers, you might need to make a judgment call about which makes the most sense. Be courteous and grateful, never defensive, with your reviewers. They are your most important resource, so treat them well.
8. Do a final editIncorporate the feedback, take a break, and then read it one more time. If you make anything other than the slightest tweaks at this point, get it reviewed again.
9. Publish and promoteCongratulations! You did it! Now it's time to make sure people read it. If you wrote a blog post, promote it on social media. Add appropriate keywords and hashtags.

If you updated documentation in response to customer feedback, let them know you fixed it and thank them for helping you improve the docs. In all cases, be sure to let your reviewers know it's published and thank them. People who are acknowledged are more likely to keep giving you feedback.

Time to jump in! You can print this list and start ticking off the steps, or you could add each step on your calendar. I like using the Self journal for planning and tracking goals. Whichever system you use, just start.

Do you have any tips or tricks for finishing a writing project? Please share them in the comments.

Recently, I was talking with our CEO, Tyler Jewell, about the importance of writing. Good writing has some obvious benefits, such as ensuring people understand your points in an email and building your personal brand. Tyler attributes much of his success to his habit of writing regularly. But then he said something I hadn't considered before: "Writing makes you smarter."

Tyler is a prolific blogger. He finds that setting aside time to focus solely on the topic you're going to write about helps bring clarity to complex topics and causes you to think about them in ways you haven't before. And when you can speak and write articulately about complex matters, others think you are smarter. But can the writing process itself make you smarter? I was intrigued by this idea, so I took the obvious next step: I decided to write about it.
Writing increases engagement in learningWhen I'm not writing regularly, I am more distracted and disorganized, and I'm less motivated to learn new things. In the Psychology Today article How Writing Makes You Happier, Smarter, and More Persuasive, Gregory Ciotti writes:

There’s a certain discipline required to create interesting written work that demands the individual be receptive and focused on finding new sources of information, inspiration, and insight. I’ve read books, listened to podcasts/radio, and watched videos I may have normally put off in order to learn something interesting that I might write about later.

Even if you don't love writing, you've probably noticed that researching a problem piques your interest in learning. If you're trying to figure out which car to buy, suddenly you start noticing all the cars on the road, you ask your friends what they like about theirs, and you start reading reviews on websites you might never have visited otherwise. You become engrossed by the topic and start absorbing information about it everywhere, which causes your brain to kick into high gear and exposes you to new information. The research phase of writing not only makes you more informed, it's also a great way to exercise your brain and make it work more efficiently in all areas of your life.
You too, engineersWhile many engineers love to write, many others are terrified to sit down to a blank page that needs to be filled with words instead of code. But writing actually has a lot in common with coding, and it’s critical for your engineering career. Mike Borozdin, VP of Engineering at Ethos Lending who previously worked at DocuSign and Microsoft, said this to Business Insider:

I would advise folks in software to do one thing, and that's write. You need to know how to express yourself. Once you create a successful piece of software, you're probably going to be writing English as much as you're going to be writing Java or Objective C.

When you're designing a feature, writing about it helps you see where there are gaps in your understanding and priorities. Do you know why you're creating this feature and what business problem it solves? Can you succinctly explain its purpose and how it works? By organizing your assumptions and conclusions in a document that you share with other stakeholders, you can be sure that you're coding it right the first time and that everyone is working from the same understanding. In other words, you'll work smarter, not harder.

Once your feature is released, writing becomes even more important. According to Borozdin, whenever his software went viral, he ended up writing probably 10 times more documentation and answers to questions than he wrote code. Writing not only leads to success; it's required once you achieve it.
Feedback is keyIt's important to know the basic rules of punctuation and grammar and to take time to structure your writing so that it flows in a logical way. (Although flawless grammar and punctuation are not always critical for conveying meaning, typos can affect how people interpret the emotion of your emails, and at worst they can lead to costly or even fatal mistakes.) Your writing should be easy to understand and not violate the hiccup rule: if you have to stop mid-sentence and re-read the sentence, it has caused you a mental "hiccup" and should be rewritten.

But have you ever carefully reviewed what you wrote (the answer to this should always be "yes") and were surprised when someone spotted a typo you completely missed? When you read your own writing, your brain fills in the gaps, making it hard to spot your mistakes. So no matter how exceptional a writer you are, get your work reviewed. Even professional editors hire editors, because they know it's the only way to improve their writing.

When you receive the feedback, put yourself in an open, non-defensive state of mind, read the feedback carefully and thoroughly, and ask questions if you don't fully understand it. You want to take in the feedback and learn from it, not just mindlessly make the corrections people give you. Over time, you'll hear those comments in your head as you're writing new content, and your writing will get better and better. This will cause people to perceive you as more intelligent than people who make frequent errors. And even though research shows there's no correlation between poor spelling and intelligence, striving for clear and accurate communication is just plain smart.
The bottom lineIn summary, a regular writing practice stimulates your brain, makes you more informed, helps you work more efficiently, and helps others see you for the smart person you truly are. So pick a topic and go!

In my next blog post, I'll outline the fundamental steps for starting and completing a writing project. In the meantime, check out my previous posts for tips on grammar, punctuation, and the joys of writing.

Collective nouns provide a way to refer to a group as a single unit. In fact, “group” is an excellent example of a collective noun; when you refer to a group, you are referring to all members of that group at once as a single unit. Other collective nouns you'll run into frequently are: team, data, network, family, and company.
Because the collective noun is being treated as a single unit, use singular verbs with it. For example, you write:
“The group isgoing to the event”
not:
“The group aregoing to the event”
Similarly, you write:
“The network of servers isoffline”
not:
“The network of servers areoffline”.  
When you follow a collective noun (“network”) with a prepositional phrase that defines what’s in the collective noun (“of servers”), it can be tricky to remember to use the singular verb (“is offline” instead of “are offline”). The reason is that your ear may cling to the last word it heard (“servers”) and think “servers is down” sounds wrong. But “servers” is the object of the prepositional phrase, NOT the subject of the sentence, and it's the subject of the sentence that the verb has to agree with.
If you see a prepositional phrase, take a look at what the sentence would look like without it, and you’ll have an easier time figuring out whether to use the singular or plural. For example, try this:
“The network of servers is down.”
Hmm, shouldn’t it be “servers are down”? Let’s remove the prepositional phrase:
“The network [of servers] is down” -> “The network is down.”
Could I say “The network are down?” Nope! The subject is “network”, not “servers” (“servers” is the object of the preposition), and the verb must agree with the subject, so it should be “The network is down.” So “The network of servers is down” is correct.
Of course, English is crazy, so there’s an exception: if you are putting the emphasis on the individuals in a group, you can use the plural verb. For example:
“After the event, the Tech Content team were trying to find their cars.”
This is the equivalent of saying:
“After the event, the members of the Tech Content team were trying to find their cars.”
In this case, it makes sense to use the plural verb, because using the singular verb would make it sound like the cars are owned by the Tech Content team, not by the individuals on the team:
“After the event, the Tech Content team was trying to find its cars.”
However, I recommend you avoid this awkwardness entirely and refer to the individuals explicitly as I did with “members” in the second example.  
Removing the prepositional phrase to help you determine whether to use the singular or plural verb is similar to a trick you can use when you’re trying to figure out whether to use the subject or object version of a pronoun, such as “and I” or “and me”.
For example:
Sam and I went to the market.He gave the feedback to Sam and me.
The first sentence is pretty easy. Get rid of “Sam and”, and you’ll quickly see that “I went to the market” is correct, not “Me went to the market.” So you know it’s “Sam and I went to the market.”
But shouldn’t it also be “Sam and I” in the second sentence? If you pull out “Sam and” again, you can try it both ways:
He gave the feedback to me. (Correct)He gave the feedback to I. (Incorrect)
Why? Because a propositional phrase takes an object, not a subject, so you must use the object form “me”. Therefore, “He gave the feedback to me” is the correct sentence, and if you add back in “Sam and”, you get “He gave the feedback to Sam and me.”
These little mental tricks of pulling out extra information from the sentence to get down to the core components of subject, verb, and object can be very useful for figuring out whether to use the singular vs. plural of a verb and the subject vs. object of a noun.
What other tricks do you use to help with tricky sentences? Add your tips in the comments below!

We’re all familiar with verbs. They describe the action or state of being. For example:

I run. (“I” is the subject, “run” is the verb) 

They crashed. (“They” is the subject, “crashed” is the verb) 

I think, therefore I am. (“I” is the subject in each clause, “think” and “am” are the verbs) 

The plane is flying overhead. (“plane” is the subject, “flying” is the verb preceded by the helper verb “is”)

But sometimes, a verb is not a verb!

A verbal is a word formed from a verb that functions as a noun, adjective, or adverb. There are three types of verbals: GerundsParticiplesInfinitivesGerundsGerunds end in "-ing" and act as a noun:

Flying is my favorite pastime. ("Flying" is the subject of the sentence) 

I love running. ("running" is the direct object of the sentence)

ParticiplesParticiples act as adjectives. There are two types of participles: present and past. 
Present participles, like gerunds, end in "-ing", but they're used as adjectives, not nouns:

The flying squirrel was amazing. ("flying" is an adjective modifying "squirrel") 

The squirrel flying across the sky was amazing. ("flying across the sky" is a present participial phrase acting as an adjective modifying "squirrel")

Past participles usually end in "-ed" or "-en":

The crashed server made us frantic. ("crashed" is an adjective modifying “server”) 

The broken windows leaked a lot of rain. ("broken" is an adjective modifying “windows”)

Don’t confuse gerunds and present participles with verbs in the progressive tense, which come after a form of the verb “to be”:

The plane is flying overhead. (verb) 

The cat was running across the lawn. (verb)

Don't confuse past participles with verbs in the passive voice, which start with was/were:

The windshield was cracked. (verb) 

The windows were broken. (verb)

Infinitives Infinitives start with “to” and end with the simple present form of a verb, such as “to fly” and “to crack”. They can act as nouns, adjectives, or adverbs.
Nouns:

To live is to adjust. 

I want to go. 

I love to fly.

Adjectives:

This is the best time to start. (modifies “time”) 

The first attempt to build the Panama Canal ended in failure. (adjectival infinitive phrase modifying “attempt”)

Adverbs:You can tell an infinitive is acting as an adverb if you can put “in order” in front of it and get the same meaning.

To win, you need the highest number of points. (adverb modifying “need”) 

In order to win, you need the highest number of points. (same thing) 

We nailed plywood on the store windows to prepare for the storm. (adverbial infinitive phrase modifying “nailed”). 

We nailed plywood on the store windows in order to prepare for the storm. (same thing)

If you look at the noun or adjective examples of infinitives, however, you can't put "in order" in front of them and get the same meaning. "I love in order to fly" doesn't have the same meaning as "I love to fly", so you know in this case the infinitive is not an adverb. Note that you use a comma after the adverbial infinitive when it starts a sentence:

To prepare for the storm, we nailed plywood on the store windows.

But you do not separate the adverbial infinitive from the rest of the sentence if it comes at the end of the sentence:

We nailed plywood on the store windows to prepare for the storm.

Don’t confuse infinitives with prepositional phrases. In infinitives, "to" is followed by a verb, whereas in prepositions "to" is followed by a noun.

I want to go. (Infinitive - "to" is followed by the verb "go") 

I went to the park. (Prepositional phrase - "to" is followed by the noun "(the) park")

So that's all you really need to know about verbals. And now I'm guessing (verb) you want to go (infinitive) to the bar (prepositional phrase) and forget all about them.

Referenceshttps://webapps.towson.edu/ows/verbals.html

In the last lesson, we took a side trip into the essentials of technical writing. Now, let's get back to some thorny grammar problems. Today, we will cover prepositional phrases, how to use pronouns correctly within them, and how to identify when a preposition is actually a particle (and why you might care). 
PrepositionsA prepositional phrase provides additional information such as when, where, and how. It always starts with a preposition like one of the following words:

in
of
to
with
on
after
for

(For a list of more prepositions, go here.)

For example, consider this simple sentence:

I drove.

If you want to say where you drove, add a prepositional phrase:

I drove to the store.

You could also use a prepositional phrase to say when you drove:

I drove to the store after midnight.

If you want to say more about which route you drove, put the prepositional phrase after the verb “drove”:

I drove on highway 101 to the store.

If you want to say more about where the store is located, put the prepositional phrase after the noun “store”:

I drove to the store on Broadway.

Notice that you’ve now nested a prepositional phrase within a prepositional phrase, which is perfectly fine. You can use several prepositional phrases to add lots of details:

After midnight, I drove with Sam on highway 101 to the store on Broadway.

A simple prepositional phrase has just a preposition followed by a noun (midnight, Sam, highway 101, store, Broadway) and any modifiers (e.g., sleepy Sam, busy store). 
If the words following the preposition include a subject and verb, though, it’s called a subordinate conjunction.
For example, here are two sentences that use the preposition “after”:

I drove after midnight. (prepositional phrase) 

I drove after Sam fell asleep. (subordinate conjunction)

PronounsIn prepositional phrases, the words that come after the preposition make up the object of the preposition. In a subordinate conjunction, however, the words that follow the preposition make up a clause, which must include (at minimum) a subject and verb. Why does it matter if it’s a prepositional phrase or a subordinate conjunction? Let’s look at an example:

I’m going with whomever. 

I’m going with whoever wants to go.

In the first sentence, you don’t have a verb after the preposition, so it’s a prepositional phrase, and the pronoun that follows the preposition must be an object. This means that if you’re using a pronoun like “whoever”, you have to use the object form “whomever”, not the subject form “whoever”.
In the second sentence, however, you have a verb, so it’s a subordinate conjunction. In this case, you use the subject form “whoever” instead of the object form “whomever”.

This causes a lot of confusion. I see this incorrect construction all the time:

Wrong: I’m going with whomever wants to go.

This is wrong because “whomever” cannot be the subject of the verb “wants”. You need the subject form “whoever” instead. 
Now, let’s make things even more confusing:

I’m going with whomever I want.

This sentence is correct! Why? Because in this subordinate conjunction, the subject is “I” and the verb is “want”. It also has an object (“whomever”), which appears at the beginning of the clause in a subordinate conjunction. If you were writing the clause as a sentence, it would be:

I want whomever.

But when the clause is subordinate, the object comes first, which can make it harder to spot the subject vs. the object:

I’m going with whomever I want.

Take another example:

I’m addressing the letter to whom it may concern.

This is a subordinate clause with a subject (“it”), verb (“may concern”), and object (“whom”). 
Here’s another construction that causes problems all the time:

Shiraz and I took the candy. 

She gave the candy to Shiraz and me.

In the first sentence, “Shiraz and I” is the subject of the sentence, so you use the subject form of the pronoun “I”. But in the second sentence, “Shiraz and me” is the object of the preposition, so you use the object form and write “me” instead. You could also say:

She gave Shiraz and me the candy.

In this case, "Shiraz and me" is the indirect object, so you use the object form "me". 
People often say “Me and Shiraz took the candy” or “Shiraz and me took the candy”, which are both wrong and make my ears hurt. But it’s even more painful when people try to sound correct and use the subject when they should be using the object, such as “She gave the candy to Shiraz and I”. (No, she didn’t. She gave it to Shiraz and me.)

So how can you remember all this? First, identify the subject by asking yourself who or what is doing the action. You will then have a much easier time figuring out which word, if any, is the object.

For example, in the candy sentence, here’s what’s going on in my head:

“Okay, she’s giving the candy, so ‘She’ is the subject of the sentence and ‘gave’ is the verb. What did she give? The candy. So that’s the object of the sentence. Now I see a preposition (to), so what follows is either a prepositional phrase or a subordinate clause. I just see nouns, no verbs, so this is a prepositional phrase, which means I need to use the object form ‘me’. The pronouns 'I' and 'me' always come after the other person, so the sentence is: She gave the candy to Shiraz and me.” 
ParticlesHere's an interesting point that won’t usually affect your writing but is nice to know: sometimes words that look like prepositions are actually part of the verb. These are called particles. For example, in the verb “sign in”, “in” is a particle, not a preposition, and is an important part of the verb. Consider the differences in these two sentences:

Be sure to sign in before you continue. ("in" is a particle) 

The sign in the office welcomes visitors. ("in" is a preposition)

The main reason you might care about identifying a particle vs. a preposition is if you’re tempted to move the parts of the sentence around. The particle must not be separated from the verb, whereas the prepositional phrase can be moved. For example, you can say:

In the office, the sign welcomes visitors.

But you cannot say:

In before you continue, be sure to sign.

Nor can you say:

Before you continue, in be sure to sign. 

Even Yoda doesn’t do this. (Awkward his speech is. Yes. Yes! Yet wise Yoda is.) 
References:https://www.englishclub.com/grammar/prepositions-list.htm

http://www.chompchomp.com/terms/preposition.htm

https://webapps.towson.edu/ows/prepositions.htm

http://www.quickanddirtytips.com/education/grammar/yoda-grammar

In this lesson, we cover some of the essentials you should keep in mind when planning, writing, and releasing documentation and training content.
Plan a release based on feedbackAt the beginning of a release, don’t just figure out what new features will be in the product and plan to doc those—also check with the product team to find out what areas they think need improvement from the last version of the documentation, and check user forums and support queries for the questions people are asking. Start working on improving this content right at the end of a release, before the next release is really underway when your time will be mostly focused on documenting new features.
Work like an investigative journalistWhen you’re first learning about a feature, work like an investigative journalist and focus on “getting the story.” Be curious and keep wondering what the user will ask next. Always ask and answer the question “why?”, and use the active voice wherever possible so that it’s absolutely clear who is doing what and when. For example, consider this sentence:

The configuration must be updated to ensure all new users can access the application.

How does the configuration get updated? Does it happen automatically when a user signs up? Does an admin have to do it?

Instead, write this:

When you add new users in the batch file, you must also update the configuration file to give the new users immediate access to the application.

Write for less technical usersDevelopers often create products with a certain audience level in mind, and usually they assume the audience is a lot more familiar with the company's technology than they actually are. In reality, users often need more hand-holding and simple instructions than developers might think. As you’re talking to an engineer or reading their spec or initial write-up, keep an image of a less-savvy user in mind and ask the questions that person would ask.

Never assume the user has read the introductory material, as they probably landed on that page by doing a web search. So make sure there are links back to the introductory material, definitions, etc. If someone unfamiliar with the product can understand it, you’ve communicated your message clearly.
Structuring a topicStart with the concepts they need to know (link off for more info), then how to do it, and then additional reference info. This follows the “inverted pyramid”:

most important -> less important -> least important

The first paragraph should follow this structure:
Basic overview of the featureWhat problem it solvesWho needs this featureExample (if needed)Why this is useful (so what?)Very brief overview of “how”Then go into details after the intro. For example:

The foo feature enables you to remotely delete all data and applications from a user’s device (also called “wiping” the device). This feature ensures that the data on your users’ devices will not be compromised if their device is lost or stolen. 

A foo agent runs in the background on the user’s device and will therefore decrease battery life slightly, so it is most appropriate for users who a) have confidential data on their devices and b) do not need to maximize battery life. 

After you enable foo on your server and install the agent on the user’s device, you can run foo from the Admin dashboard when you need to wipe the device.

To enable foo on the server:
1. (instructions)
2. (instructions) 

To install the foo agent on a device:
1. (instructions)
2. (instructions) 

To remotely wipe a device:
1. (instructions)
2. (instructions)

Likewise, you should name the topic based on what someone is trying to do:

Remotely wiping a device

is more informative than:

Using the foo feature

Refine the contentWarnings, gotchas, and prerequisites should appear before you tell them how to do something, never after. For example, imagine the support calls you'd get if you wrote this:

To delete data:  

1. Navigate to foo > bar.
2. Enter your admin code.
3. Click Delete.
4. When prompted, click Yes to proceed.  

Note: Only click Yes if you want to delete all the data in your system. You should make a backup before you do this.

Instead, you should write something like this:

To delete all your data: 

WARNING! This procedure will permanently delete all the data in your system. 

1. Make a backup of your data.
2. Navigate to foo > bar.
3. Enter your admin code.
4. Click Delete.
5. If you are sure you want to delete all the data in your system, click Yes to proceed. 

For information on restoring the data from your backup, see Restoring Data.

Notice the intro now indicates this will delete all your data, making a backup is part of the procedure so it's harder to miss, and the confirmation step reiterates that this will delete all your data. Additionally, I've added a helpful link after the procedure that tells you how to restore your data in case you went through these steps and realized you didn't actually want to do this.

This approach puts the most important information first (there's that inverted pyramid again), adds cues to help remind the reader what this is going to do, and anticipates a scenario where someone made a mistake. By thinking through what the reader wants to do and may inadvertently do, you can refine the content to be as helpful as possible.
Simplify the languageCut out all extraneous words. For example:

made arrangements for -> arranged

made the decision -> decided

made the measurement of -> measured
performed the development of -> developed
is working as expected -> works as expected

Break up long sentences and paragraphs. Use bulleted lists instead of listing options in a sentence, and use bold text to highlight the main points. Remember, readers aren’t here to read; they’re here to get the information as quickly as possible.

There's a very nice example of this here.[image error]
Keep the reader’s goal in mindWhy are they here, and what do they want to know? For example, look at this sentence:

This law was introduced in 2011, after a long, drawn-out process of appeals, to ensure that agency workers are given some of the same employment rights as their full-time counterparts.

In this example, the end goal is for the reader to find out about employment rights. The information about the legal appeals process is not essential, so remove it:

This law was introduced in 2011 to ensure that agency workers are given some of the same employment rights as their full-time counterparts.

Many developers want to provide as much specific detail as possible, but this can come at the expense of readers understanding the main point. For example:

The system can process multiple requests per second. One customer processed 5,165,345 requests per second. Another customer processed 10,725,335 requests per second.

Instead, write:

The system can handle enormous loads. One customer’s implementation regularly processes over 10 million requests per second, which was twice as much as their previous system could handle.

Remember, people want information, not just data. So give data as needed but always explain what it means. In this case, people want to know if it can handle very large loads, and giving the higher number as an example is sufficient, plus adding some info about why this number is significant (dig in and find out more about the example…in this case, it’s assuming you did your research and discovered that the load was twice the customer’s previous capacity).

Use the inverted pyramid for sentences as well. For example, instead of this:

You can enter the information manually each time, but it’s better to configure it as a property.

Write this:

Configure the information as a property so you don’t have to enter it manually each time.

Use graphics wiselyUse screenshots when needed to orient the user, but don’t include them in every single step, or they can easily get lost. Animated GIFs are especially nice for showing how to navigate somewhere that’s hard to explain in text, but keep in mind that you must also add Alt text to all graphics to describe what’s happening in the image for those who are visually impaired.
Examples are crucialHave you ever noticed that you may read the first sentence describing a feature and still not really understand what it is, but then the next sentence gives a real-world example that helps you attach the concepts to something tangible? The best way to clarify your content is through examples. Not everything merits an example, while more complex concepts may need more than one example. When you’re documenting properties, giving examples of actual values helps a lot. And when describing how to write code, samples are essential.
Test all the stepsIt’s critical that you test and document all the steps in a procedure and not just rely on the steps that were given to you. People who know the technology well will often leave out small but important steps (such as restarting the server after making configuration changes), which results in support queries.
Review your contentWalk away and then come back and re-read your work to catch mistakes. And then always get a second pair of eyes on your writing. No matter how experienced you are, you will always make mistakes you can’t see, so peer reviews are important.

Likewise, whenever possible, get someone new to the technology to test out the procedures you’ve written.

Lastly, get a subject-matter expert to review your content to make sure you didn’t miss anything, and also ask for best practices that users should know. This will take your content from covering the basics to being more deeply insightful and useful to advanced users.
Get feedback from usersLook at the support queries and questions on user forums to see what people are asking and where they’re running into trouble.
SummaryOur ultimate goal is to reduce support queries to zero, so: Ask good questions up frontStructure the content using the inverted pyramidWrite simple, accurate, fully tested content that gives information and not just dataProvide good examples and graphics where neededInclude best practices that will help users go beyond the basic stepsThis approach will help ensure the users are successful and the support people are bored.
Additional resourceshttps://medium.com/@limedaring/five-tips-for-improving-your-technical-writing-and-documentation-47353723c8a7

http://www.copyblogger.com/technical-writing/

http://www.wikihow.com/Master-Technical-Writing

http://web.mit.edu/me-ugoffice/communication/technical-writing.pdf

http://idratherbewriting.com/2014/06/20/10-technical-writing-principles-to-live-by/

https://tech.co/tips-technical-writing-2015-11

In the previous lesson, we covered hyphens and dashes. Now, we're ready to move on to a tricky topic: coordinate vs. cumulative adjectives.

Coordinate adjectives individually modify a noun and are separated by a comma. For example, look at “heavy” and “bulky” in the following sentence:
The heavy, bulky box was awkward to carry. You can tell that they're coordinate adjectives because they would still sound correct if you used “and” between them, such as:
The heavy and bulky box was awkward to carry. or if you changed their order:
The bulky, heavy box was awkward to carry. Also, if you have adjectives from the same category, such as two opinion adjectives or two size adjectives, you use a comma. For example:
The beautiful, elegant box sat on the mantle. The gigantic, enormous box was impossible to lift. Note that adjectives from the same category are rare in technical writing, as they’re mostly used to be emphatic. In tech writing, we aim to be precise but concise.

Cumulative adjectives are used when the adjectives are from different categories (e.g., age and size) or when the final adjective before the noun creates a compound noun. This is especially true when you specify origin (nationality/religion). For example, "and" sounds wrong between these adjectives, so you don't use a comma:
Correct: She was a smart Muslim woman Incorrect: She was a smart and Muslim woman But you could say “She was a smart and beautiful woman”, so these would be coordinate adjectives instead of cumulative:
She was a smart, beautiful woman. Here comes the crazy part: cumulative adjectives must be in a specific order based on their category. This order is as follows, with examples for each category:
Opinion: good, attractive, delicious Size: large, small, enormous Age/Condition: old, new, modern, worn Length or shape: long, short, square Color: red, blue, green Origin (nationality, religion): American, Muslim Material: plastic, wooden, cotton Purpose: electric (wire), tennis (shirt) For example, these are in the correct order:
An attractive young American lady A modern Japanese electric car A big square blue box But the following examples are NOT in the correct order and sound all wrong:
An attractive American young lady A Japanese modern electric car A blue square big box This is hard to memorize, and it just takes practice. Most native English speakers have no idea that this order even exists; they just do it naturally and know something is wrong when they hear them out of order. I recently told a friend about this order and he laughed at me, refusing to believe this rule exists, until I started rearranging adjectives in a sentence. His eyes got wide, and he quickly changed the subject.

There are sites that show a much longer and more detailed list of categories, but it's simpler to stick with the more concise list above. In fact, if you search for "cumulative adjectives", you'll find a different list on most pages. I've chosen the list that I think covers the most important categories.
SummaryCoordinate adjectives are separated by a comma and sound fine if you change their order or insert "and" between them instead of a comma. Cumulative adjectives are not separated by a comma and must be placed in a specific order based on their category.

In the next lesson, we'll take a break from punctuation and talk about the essentials of technical writing.
Additional resourceshttp://wilcoxediting.com/articles/2009/04/07/comma-between-adjectives
https://www.khanacademy.org/humanities/grammar/parts-of-speech-the-modifier/adjective-order-and-commas-with-adjectives/v/commas-and-adjectives

In the last lesson, we took a deeper look at commas. In this lesson, we will explore the difference between hyphens, en dashes, and em dashes. HyphensA hyphen connects two words that are closely related and are acting as a single word. For example:
Two-thirds of survey respondents said they needed additional training.This number is toll-free. However, in some cases, you only connect the words with a hyphen when they are acting as an adjective modifying the word that follows them:This architecture supports high availability when traffic increases. (“availability” is a noun, and “high” is an adjective modifying it)To handle traffic spikes, design a high-availability architecture. (“high-availability” is a compound adjective modifying “architecture”)Next, you check in your files. (“check” is a verb, “in” is an adverb modifying “check”)The server sends a check-in notification. (“check-in” is a compound adjective modifying “notification”)Words that are hyphenated often end up as open compounds (that is, they have a space instead of hyphen). “Open source” is an example of an open compound:
This software is open source.This open source software is free to use. (No hyphen between "open" and "source")And eventually, they may even become a single word. For example, "email" evolved like this:Electronic mail -> e-mail -> email
“Log in” is still two words when it’s a verb:You can now log in to the application.But it’s a single word when it acts as an adjective:
Your login information was sent to your email address. Note: Why wouldn't you say "You can now log into the application"? Aren't you supposed to combine "in" and "to" when they're next to each other? In cases like "Look into this for me", the answer is yes. But in this example, "log in" is a phrasal verb, meaning that the verb "log" and the adverb "in" must go together and act as a single verb. Therefore, if you combined "in" and "to" to make "into", you would be splitting the "log in" phrasal verb in half, and "log" would be sad that "in" ran off with that scoundrel "to".

The Microsoft Manual of Style (and some other style guides) instructs us NOT to use hyphens after “-ly” adverbs:
These are often-asked questions. These are frequently asked questions. (No hyphen after an "-ly" adverb)Irritating side note: Some grammar guides say you DO hyphenate after an “-ly” adverb IF the second word in the compound is the past participle. In this case, “frequently-asked questions” would require a hyphen, since “asked” is the past participle of the verb “to ask”, whereas “frequently upsetting incidents” would not use a hyphen, because "upsetting" is the present participle (not the past participle) of the verb "to upset". Confused? Don't be, because we’re going to ignore that stupid rule and stick with the Microsoft Manual of Style!
DashesThere are two types of dashes: en dashes and em dashes. En dashes are longer than hyphens but shorter than em dashes.

-    hyphen
–   en dash
—  em dash

En dash
En dashes are uncommon. They connect two things that are related to each other by distance, essentially replacing the word “to”. For example:
Take the San Francisco–New York flight.I read this in the May–September issue of the magazine.This certificate is valid 2017–2018.Note: If you want to use "from" in the last example, use "to" instead of the en dash. For example:
This certificate is valid from 2017 to 2018.OR
This certificate is valid 2017–2018.But NOT:
This certificate is valid from 2017–2018.
To type an en dash, see: https://www.howtotype.net/symbol/en-dash/

Em dash
The em dash is longer and is more common than the en dash. It sets off and emphasizes additional information in the sentence and can be used in place of commas, a colon, or parentheses—as I just did in this sentence. For example:
When the car was finally delivered three months after it was ordered, she no longer wanted it.When the car was finally delivered, three months after it was ordered, she no longer wanted it.When the car was finally delivered—three months after it was ordered—she no longer wanted it. The second example uses commas to offset and emphasize the phrase. The third example uses em dashes to emphasize it even more, indicating how irritating it was that it took three months for the car to arrive. Here's an example of an em dash replacing a colon:
The white sand, the warm water, the sparkling sun—this is what brought them to Hawaii.To type an em dash, see: https://www.howtotype.net/symbol/em-dash/SummaryHyphens connect two words that are closely related. En dashes connect two things that are related by time and replace the word "to". Em dashes set off a part of the sentence to give it extra emphasis. 
In the next lesson, we will look at coordinate vs. cumulative adjectives.
Additional resourceshttp://www.thepunctuationguide.com/hyphen-and-dashes.html

In this continuation from the previous lesson, we will dig deeper into using commas in technical writing.
Avoiding the comma splice A "comma splice" is the incorrect usage of a comma to separate two independent clauses. (Reminder: an independent clause has both a subject and a verb.) For example:
Incorrect: The server has started, you can log in.
The first clause has the subject "The server" and the compound verb "has started". The second clause has the subject "you" and the compound verb "can log in". Therefore, they are both independent clauses.
When there are two independent clauses, you can separate them in the following ways:Use a period if they stand alone as separate ideas: The server has started. Log in using your credentials.Use a comma and a conjunction if they are connected ideas: The server has started, and you can now log in.Use a semicolon if they are closely-related ideas: The server has started; you can log in.(You could also use dashes, but we won't cover that until the next lesson.)
Semicolons can lead to long and somewhat ambiguous sentences, so we tend to avoid semicolons in technical writing. It's better to create two separate sentences with a period, or use a comma and a conjunction that clearly shows how the ideas are connected. For example, consider this sentence:
The server is starting; you can log in now.
Does this mean you can log in because the server is starting or in spite of the fact that it's still starting up? A comma and conjunction make the two different meanings clearer:
The server is starting, so you can log in now.The server is starting, but you can log in now. Using commas with adverbsAn adverb modifies a verb, an adjective, or another adverb. They often end in "-ly", which makes them easier to spot. For example:
He ran swiftly. ("swiftly" is the adverb modifying the verb "ran")

The really fast connection made surfing the web a lot more fun. ("really" is the adverb modifying the adjective "fast", which is modifying the noun "connection")

He ran incredibly swiftly. ("incredibly" is the adverb modifying the adverb "swiftly", which modifies the verb "ran")
As you can see, you do not use commas between adverbs and the words they modify. The exception is when you repeat an adverb for emphasis, such as: 
The really, really fast connection made surfing the web a lot more fun.
But don't do this in technical writing, please!
Put the adverb as close to the word it modifies as possible. For example, "Swiftly he ran" is fine in poetry, but it sounds awkward in technical writing. Worse, moving the adverb away from the word it's modifying can also create confusion in more complex sentences. An exception is when you put it at the end of an imperative (command) sentence to add emphasis:
Return to the front desk immediately.
You could also write "Immediately return to the front desk", but it sounds more like a general instruction and less like an urgent command. 
This brings us to sentence adverbs, which usually do appear at the beginning of the sentence and are followed by a comma. A sentence adverb modifies the sentence as a whole instead of a specific word. It is useful for expressing an opinion. For example:
Incidentally, your father dropped by earlier.Sadly, the ball was canceled.
When I write these sentences, I'm expressing the opinion that the information I'm giving you about your father stopping by is an incidental aside, and I'm expressing sorrow that the ball was canceled. You can also put sentence adverbs in the middle or end of the sentence to put less emphasis on them:
Your father, incidentally, dropped by earlier.
The ball was canceled, sadly.
Notice that wherever you put the sentence adverb, it's always separated from the rest of the sentence by commas. Using commas with imperativesAn imperative is a command, such as "Type your password at the prompt." The implied subject of this sentence is "You", and the verb is "type", so it is an independent clause. Even the one-word sentence "Go!" is an independent clause, because the subject ("You") is implied.
When you have two imperatives whose ideas are closely related, even though they are independent clauses, you don't need a comma between them. For example:
Type your password and press Enter.Change the Foo property to BAR and click OK.
If the second clause is long, or if it is more of a separate step, you can use a comma. To avoid confusion, I often insert the word "then" when I'm using a comma and conjunction between imperatives. For example:
Change the Foo property to BAR, and then select the action type. SummaryYou might be wondering why we have all these rules for commas. In technical writing, our goal is to get the information as quickly and accurately as possible into the reader's brain, and using commas correctly helps a lot. Just remember that even if a sentence is punctuated correctly, you must rewrite it if it violates the hiccup rule. 
In the next lesson, we will cover hyphens and dashes. Additional resourceshttp://www.quickanddirtytips.com/education/grammar/comma-splice
http://theeditorsblog.net/2016/02/21/a-tale-of-adverbs-and-the-comma/
https://writingwithsharonwatson.com/commas-compound-sentences-coordinating-conjunctions/