If Johnny Can't Read, How Do You Write a User Manual for Him?

Can people read your docs?

The first task any accomplished technical writer has to do is write for your audience. It may sound simple. When I thought about people living all over the world one thing became clear to me: can they read our documentation?

Readability is something that has been studied for years and I will give a brief summary as to what research has shown.

Studies prove that people respond to information that they can easily understand. Of course the question is: Are we writing content that the average person can easily read and understand? Do we  even know? If people are not connecting with our content, one of the reasons could be is that we are writing “over their heads” and trust me when I tell you that this happens more often than you think. In an effort to sound superior, intelligent, or as an “expert” in our fields – many  will “overwrite” content, or use "big words" in order to consolidate the screen real estate of the printed material.

A simple way to check your document to see if it is "easy to read" is to use a readability test. Many different tests have been created. The three most popular are:

• Flesch Reading Ease Test 
• Flesch-Kincaid Reading test 
• Gunning Fog Index

Summary of the Popular Readability Tests

Flesch Reading Ease test

Rudolph Flesch, author of Why Johnny Can't Read: And What You Can Do about It  created the Flesch Reading Ease Test as a way to further advance his feeling that American teachers needed to return to teaching phonics as opposed to sight reading (whole word literacy). His work and advocacy for reading and phonics were the inspiration for Dr Seuss to write The Cat in the Hat. The Flesch Reading Ease test was This test tells you how easy it is to read the text. The algorithm is as follows:

https://upload.wikimedia.org/math/0/0/d/00d5ec44a95797716b622924176ec6a4.png

The resulting score is interpreted as follows:

Score	Definition
90.0–100.0	Easily understood by an average 11-year-old student
60.0–70.0	Easily understood by 13- to 15-year-old students
0.0–30.0	Best understood by university graduates

 https://en.wikipedia.org/wiki/Flesch-Kincaid_readability_tests and https://simple.wikipedia.org/wiki/Flesch_Reading_Ease

What does this mean?

• The lower the score, the harder the text is to read
• 65 is the "Plain English" rating
  
  

How does this score measure up to well-known publications?

• Reader's Digest - 65
• Time Magazine - 52
• Havard Law Review >40

Flesch-Kincaid grade level test

The Flesch-Kincaid reading test was the result of a collaboration between Rudolph Flesch (mentioned above) and J. Peter Kincaid. J. Peter Kincaid was an educator and scientist who spent his time working in academia or researching with the US Navy. J. Peter Kincaid developed his version of the readability test while under contract for US Navy in an effort to estimate the difficulty of technical manuals. The Flecsh-Kincaid grade level test translates the test to a US grade level which makes it easy for people to judge if the material is readable by others. The algorithm is as follows:

 https://upload.wikimedia.org/math/a/3/a/a3a80e6e52fda2b5f7647a451c9c6c13.png

The result corresponds to a US grade level.  So once you have calculated the score you know immediately who can understand your writing. For example, President Obama's state of the union address has a grade level of 8.5, however the Affordable Care act has a readability level of 13.4 (university or higher). Here is the readability of some popular books, the results may surprise you:

• Goodnight Moon - Margaret Wise Brown - 2.8
• The Old Man and the Sea - Ernest Hemingway  - 4.1
• Harry Potter and the Deathly Hallows - JK Rowling - 7.8
• Good to Great - Jim Collins - 10.4

Gunning Fog Index

The Gunning fog index was created in 1952. The algorithm is as follows:

https://upload.wikimedia.org/math/2/4/e/24e74bc62f64f038ca52eeef2aa3fcc6.png

This index is not perfect as some words such as university are complex, but easy to understand, while short words such as boon may not be. Given that, the results can be interpreted as follows:

• A fog score of >12 is best for HS graduates
• Between 8-12 is ideal, closer to 8 is better
• <8 is near universal understanding

Why should I care about the readability of my writing?

To be honest, if it is too hard to read, then no one will want to read it. The sad truth is that approximately 50% of Americans read at an 8th grade level and sadly about 25% at the fifth grade level or lower. The higher the grade level, the less that can read it. If you have to struggle to read something, your experience with the content is a negative one. This negative experience will make you less likely to recommend the content to someone else. Think about it, have you ever recommended to someone to a book you did not enjoy? The same can be said about documentation. If readers struggle to read it they will not tell others about it.  

How do I calculate the readability of my writing?

There are several ways to calculate readability.  The easiest way to calculate it is within your word processor or editing tool. Since Publican version 4.0.0 and https://bugzilla.redhat.com/show_bug.cgi?id=1031364, you can run the following command in Publican: $ publican report --quiet, which will generate a reliability report.

If you are using vim as your text editor, plug-ins are available, thanks to Peter Ondrejka. They can be downloaded and installed from Git https://github.com/pondrejk/vim-readability. A similar plug-in for gedit is available at https://github.com/ilmanzo/gedit-plugin-gulpease as well.  If you just want to check without using a plugin you can always paste the text in https://readability-score.com/. Feel free to check these out and let me know which works best!

The final word

Keep it simple sweetheart! The easier it is to understand and the better it is written the more people will enjoy your writing. What’s the point in writing something that no one reads? As Rudolph Flesch would say if Johnny can’t read it, why write it? And for those of you who are curious, this article has a readability of:

• Flesch - 68.5
• Flesch-Kincaid - 6.9
• Gunning Fog - 9.3

Once you know the readability of your writing, you can try to simplify it. I will give some ideas on how to do that in my next post. Stay tuned!

Resources:

• https://contently.com/strategist/2015/01/28/this-surprising-reading-level-analysis-will-change-the-way-you-write/
• https://readability-score.com
• https://en.wikipedia.org/wiki/Flesch-Kincaid_readability_tests 
• https://simple.wikipedia.org/wiki/Flesch_Reading_Ease 

Welcome to Holland - my story (part1)

This is a letter I should have written a long time ago. http://www.our-kids.org/Archives/Holland.html wrote a blog post a while ago describing that having a special needs child is like preparing for Italy and then landing in Holland. Here is my travel record:

When I got pregnant we were so excited. We already had an adorable little girl so adding another child to the family made us very happy. Finding out a few months later that we were having a boy made us even more excited. In fact, when we finished with our ultrasound, I called our parents and told them "It's a bris instead of it's a boy". The excitement grew as the pregnancy progressed. The pregnancy was textbook and everything went as it should. The only blip on the radar was a single incident that his heart rate was low and I had to have some extra monitoring, but all was good. My husband was the typical dad to be all a glow in that he would have someone to carry his family name, someone to teach how to hit a ball, all the typical dad thoughts about "my son".

Like all expecting mothers, I read all the books, watched what I ate, and thought about how to decorate his nursery in our home. As I was superstitious, I didn't add anything to his room until after he was born. I did go and order some items to get us started that would be delivered after delivery. When I finished working in my 39th week, I thought OK I am ready. My bag was packed from week 36, the freezer was stocked with food, and everything was in place. All we needed was a baby.

On the day of his due date I went into labor. 18 hours later our son was born. I remember it was a cold Sunday afternoon on December 6. He was born at 4:30 PM. He weighed about 3.5 KG and had a head full of hair. How much joy I had over hearing his cry. He was born at Hadassah Hospital Har Tsofim campus. The hospital policy was that the first 6 hours after birth the babies had to be in the nursery. This was fine with me as I was exhausted. I went to sleep and woke up just before 8PM. Jason had gone home to be with Talia our oldest and to make phone calls. I went to the nursery to see our baby. When I got to the nursery, our son was not with the other babies. Nervously, I scanned the room. After what felt like minutes but was probably seconds, I found him. He was wrapped in a swaddling blanket and was in a warming bassinet. The nurse must have seen a worried look on my face because before I could even say anything she said, he's a bit cold no need to worry. I took him back to my room so we could begin our "rooming in". He was very sleepy and I thought "OK I am tired too, I will give the little guy a break".

He barely woke up that night but he did breast feed a few times although he had a lazy mouth and couldn't really latch on properly. The next morning, Jason went to work leaving me alone in the hospital with the baby. He seemed perfect! He was chubby, cute, and had a very pink complexion. He wasn't fussy and he loved to be held. When afternoon arrived, his big sister came to visit with Jason. Talia loved her little brother and was so excited to hold him. She couldn't wait to bring him home and when I told her "tomorrow" she jumped up and said - yay!"

As a gift Talia got a "big sister" sweatshirt from her little brother. The next day the doctors made rounds and I was cleared to check out. They told me that the pediatrician had to sign out the baby so brought him to the nursery for the doctor to check him and to run the necessary blood tests. And then I waited... and waited. After what seemed like forever the pediatrician came in my room said "you will go home tomorrow" today we need to run a test. I asked what was wrong and the doctor said "there is a murmur in his heartbeat" and then he paused and said "it is common so don't worry. we are running an echo cardiogram and we are sending it to Hadassah Ein Kerem so that the cardiologist can read the results. He made it seem as if it was a standard procedure. As I had never had a child with a murmur before I thought, OK he must be right and called everyone to let them know we would be in the hospital for one more day.

The next day took forever for us to get cleared to go home. In the end our son did indeed have a heart condition. He had 2 small holes in his septum that separated his right from his left ventricle. This type of defect is called a VSD or a Ventricular Septum Defect. The doctor assured me this was very common and thought that it would close on its own. Ventricular septum defects are among the most common congenital heart defects, occurring in 0.1 to 0.4 percent of all live births and making up about 20 to 30 percent of congenital heart lesions. According to http://www.cincinnatichildrens.org/health/v/vsd/, Ventricular septum defects are probably one of the most common reasons for infants to see a cardiologist." I put my trust in Dr. Rein the cardiologist and Jason and I brought our baby home.

Our house was filled with people by the next day. My parents arrived from NY, Jason's parents came from Ra'anana. Jason's sister lived around the corner and my brother was still in the US. With a house full of guests and our baby at home, all we needed now was a bris. I mean it is what every parent of a newborn boy thinks about, isn't it. A couple of days following our baby's birth it became apparent that a bris shouldn't be the thing we should worry about.
(end of part 1)

The evolution of a technical writer - from a nobody to a name

As a technical writer in Israel, at one time or another, you are asked to do any or all of the following:

• Proofread confidential letters between members of the board of directors 
• Edit PowerPoint presentations for everyone in the company, including the CEO
• Translate documents into English 
• Edit job offerings 

And as this newbie technical writer you may think to yourself, "Is this what I am meant to do?" The answer clearly is no, but how do you transform yourself from someone who becomes less of a lackey and more of an authority? How do you change the paradigm from being called the "technical writer" to "the name". Meaning if someone was to ask anyone in your company a question you know the answer to and they didn't know the answer, would they tell that person to "go to the technical writer" or would they say "Go to <your-name>". A name has meaning and position, everyone wants to be in a place where everyone knows your name. 

There was even a TV show in the 1980s centered around the concept. Hopefully you know by now that the place where everyone on TV knew your name was called Cheers.

Wouldn't you love to work in a place like the bar that Norm and Cliff went to? Don't you want everyone to yell your name when you come to work? Yes that can happen. Just as Norm was the element that held the bar together (probably because his tab was larger than anyone else), you too can be the glue to your development team, customer service team, QA team, Product Management team, etc and can be the one integral person who is in the know and holds the team together.

By now you are either laughing to yourself, or have ignored me completely because you think that this paradigm shift is not possible. Not only is it possible, but it has happened. Just as it happened to me, it can happen to you as well. Not every solution I am going to present to you will be possible for you to do, but the more of these ideas you are able to do  the easier it will be for you to become "the name".

1.  Be in the know, not only now but all the time 

This may be a bit challenging at first, but the more information you know the more you can share. This means you need to be involved or at least aware of every decision being made about the products you document. Become a fly on the wall at lots of meetings, especially meetings where decisions are made. If you have managers above you who are attending the same meetings, you may opt out of them thinking - X has it covered for me, but what that does is help X become "the name" and you become the person on X's team. If there are meetings you simply cannot attend due to timezone/conflict, make sure you read the minutes and get involved in other channels. You should be at the following meetings:

• Planning meetings
• Progress meetings
• Design Reviews
• Customer Reviews
• etc...

You can spend your entire life at meetings, so choose the meetings that will give you the biggest reward. By that I  mean the meetings that allow you to participate and quickly become a part of the agenda. If the teams you work with agrees to have  a dedicated "docs liaison" to keep you up to speed following their meetings, it lessens the number of people you have to interact with on a daily basis, but don't allow the liaison to become "your voice" for all the meetings. It is best if you are personally involved. After all, it is YOUR NAME you are trying to build here! 

2. Change from being the fly on the wall to a mosquito and then evolve into a butterfly 

Once you have made everyone used to your presence at meetings, start becoming a voice at the meetings. Whenever the opportunity rises, make sure that all parties are thinking about the documentation impact and about the customer. At first you may think you are a nag (ie the mosquito buzzing in someone's ear), but if you persist and make sure that everyone knows who you are and why you are there and the impact you can make on them and on the customer as a whole, the more of a name for yourself you will make. Some suggestions you can use to make this happen include:

• Keep your name in the front of their minds - this will help you everywhere you are and everywhere you go. For those of you who are shy it will be hard, but it will make you on everyone's mind. Just make sure that the feelings associated with your name are positive. 
  
•  Exceed expectation - if you want to become the
  "Go-To-Guy/Gal" (GTG), you will need to go beyond what is expected. Let them see first hand how your services matter, and how you are the go-to person and not the go-for person.  This can be done by committing for x and giving 2x. I am not advocating under committing on projects, but I do think that you should give more than 100% to all you do commit to do. Treat your position like a profession and not like a job. Technical writers provide a service to customers. Consider yourself a service provider, not only to customers but to the rest of the company as well.
• Blog, podcast, or do something else than "just guides" - this has two benefits. First it helps you diversify and collect additional skills and second it lets others see you as more than just a user manual author. Speak at meet-ups, conferences or whatever you can do to round out your portfolio. Become the one who is not only in the know but the one who can do it all. You can even give internal or external training sessions, or create how to guides, and other information pages for your company staff and customers.
• Give people a reason to look for you and recommend you - Make sure to assign yourself one or two action items at every meeting (if at all possible). This way you can report on them at the next meeting giving you a purpose for attending. Once you become "the name" this happens naturally. If it hasn't then you need to do things for people to make an everlasting positive impression. 

If you are thinking "this sounds so much like brand marketing!" it is because it is. The exception is you are the brand you are marketing! 

3.  Weave a fabric of teams together where you are the tailor 

If you have gotten to this point in your career you are in a good place. You are reaping the fruits of your labor. It may take a year, five, or fifteen, but when you get to this point in your career it feels totally awesome. When this happens you can expect any or all of the following:

• Developers will come to you with ideas about a new feature and ask you how you think it will effect the customer.
• Customer Service will come to you and invite you to visit an on-site installation.
• Collaboration is abundant. You will find yourself working on teams that you never thought would value what you think and respect what you do.  You are the glue that holds it all together.
• Everyone will want to know the documentation impact (at the beginning of the product development cycle (ie. the Planning Phase))
• You will be able to make suggestions on how to improve the product without feeling the need to explain yourself
• Individuals when asked will say "Oh you need to go see ----Insert your name here----, about that he/she knows"

When that happens, you have reached the nirvana level of brand-marketing. Enjoy it, you have worked hard to get there! For me working at Red Hat it wasn't only possible for this to happen but did happen and it will for you as well if you make sure you are a name that all can remember. 

Good luck and please share your branding story.

Purim Grinch

There have been many things I love about Israel, but Purim pushes my patience (nice alliteration!) Anyway, Purim in America if you are lucky is a 1-2 day holiday max. One day for a purim carnival at Hebrew school and one day on Purim itself -sometimes the same day if Purim is on a Sunday. Here in Israel, Purim is truly a holiday that takes over. Kids start dressing up way before the holiday comes in. Parties, parades and performances abound. Packages for the poor, soilders, Sderot, are made. Now don't get me wrong, it's not that I don't want to support all of these things, it's just too much. I am sure that working parents can understand my point. I mean there has to be a limit. And if all these things are going on, when are the kids learning.... I mean isnt't that why we send them to school, to learn?

It is now a week before Purim. All of my kids are in different schools and each school has a different schedule and different theme for the day. This means I need to prepare different costumes and buy different accessories to fufill these requirements. It gets to be expensive and this doesnt even include the costume that is worn on Purim which has to be different form those worn all week.

Their schedule looks like this:

Sunday

• Aliza - funny Hat, glasses, and Tie


• Rafi - nothing


• Talia - Indian

Monday

• Aliza - sports day


• Rafi - nothing


• Talia 70's

Tuesday

• Talia - pajama day

What's in a Name?

I find it awfully ironic, that I the one who is called creative, cannot for the sake of my sanity derive a name for my new business.

In the begining there was Triple C cakes, but 3C is already a well-known (not to me mind you), computer company.

Then I came up with Masterbis....but that didn't flow so well off the tongue.

then there was CakeCrafters

Kitchen Crafters

and even Mishuga (now you know I'm nuts!)

but nothing, is working....

Even more stressing is I have orders to fufill and I need a name for this business...

For some reason, I don't know why, I don't like anything with just my name in it.

so anyone listening...? come up with a name, and I will make you a cookie basket!

Signing off for now...

A New Beginning

For some time now, weather you know or not, I have been searching. What for I am not sure. Somedays, I feel like Don Quixote sitting on his horse searching for the beautiful Dulcinea. On days like these, I am more likely to see windmills. Other days I get an idea, and I think this is IT! Then after bouncing the idea around in my head, I give up and think it is the impossible dream. Why it is I don't pursue these ideas is I guess another blog altogether or something me and my future therapist will have to discuss. The more important thing is I have an idea and this time, I think it may be a good one.

I have known for a long time that I am a creative person, with artistic skills that are untapped. I have had many hobbies centered around art. I have painted, sketched, and sculpted. I have done scrapbooking and even had a small business centered around it, selling Creative Memories products.

Recently, I went on a weight loss program and at the culmination, at the request of my DH Jason, I treated myself to 2 Wilton Cake decorating classes. I was suprised how quickly I was able to understand and execute what the teacher was teaching, as I do not consider myself to be that coordinated when it comes to hand-eye control. Anyway, I wanted to take the 3rd and 4th class, but they weren't offered here in Raanana. This however, did not stop me from making cakes for family and friends.

In late May, I was hired to make a cake for a collegue of Jason's. I made an F-16 shaped cake for a Sheva Bracha. It came out quite nice. A week later, I went to a sugar sculpting class and made Talia's birthday cake. The next week I made a cake for Talia's end of the year party (a white board and eraser). The week after I made a swimming pool cake for a friend who hired me to make her daughter's cake. A few days later I made the end of the year cake for Aliza's class. We also were invited for a Tex-Mex shabbat lunch and made taco cakes! In addition, I also made cakes for a simchat bat (see below) June was a hetic cake month! After making 8 different cakes...I needed a rest.

In August, I made a sheetcake to say goodbye to my brother and his family as they were moving to Modi'in. The shul was making them a kiddush and I donated a cake. The cake was such a hit, I was asked to do the Shalom Kitah Aleph ceremony desserts.
This will be for September.

As if that was not enough to keep me busy, the summer has also been "quite repoductive" for many of my friends and their children. In made a baby bassinette cake and flowered cake for my friend Penny who became a safta for the first time. The cake was received with amazing reviews.

Then my friend Debbie became a Safta to 3 (twins for one daughter, single to the other) within 2 months time which gave me the opportunity to try something new. I decided to branch out from real cakes to diaper cakes. OK I know what you are thinking....gross diapers...not really. the result is beautiful trust me. OK don't trust me just look here at one of my latest creations made for my boss who had her second baby recently....



OK so here I am in a quandry...do I sit and wait for orders to come in, or do I make a business for myself and see where it goes?


If I am going to make a business, what to call it?
Before I decided on the Diaper Cake side, I had a name...see picture of business card above, but now I am not sure it fits...

I mean, how do you combine diaper cakes and real cakes into one business?

Should it be done? Can it be done? only time will tell!

Thanks for listening!

Pesach 2010

As my friend Rachel so elequently put it, "I survived Pesach 2010" and it should be made into a t-shirt.

In the same frame of mind, I think Survivor should have a Pesach series.
a 10 day survivor contest, where contestants have to do the following:
1. clean a house for pesach while children sprinkle cookie crumbs in the same place you just cleaned.
2. try to find kitniot free foods in Israel (especially vegetable oil, ketchup, and mayonaise).
3. experience most of the 10 plagues (especially the lice)
4. cook a seder meal whilst your oven breaks
5. entertain seder guests and keep everyone sober enough to make it home w/o a WWI (walking while intoxicated).
6. greating your own horseraddish (w/o a gas mask or goggles).
7. planning and executing hol hamoed entertainment for the family
8. changing the kitchen back to hametz before the pizza delivery guy shows up at the door.
9.Remembering to count omer
10. Exodus from Egypt....
anything else that can be thrown in...