Judicious use of Screenshots

Screenshots are images; and images, as we all know, are bulky. How many of us prefer bulky documentation folders that eat away into our disk space and slow down the response time of programs? So, the question you need to ask is this – are screenshots necessary?

Screenshots are a must in printed user manuals. But do you really need them in your online help? First, let’s try and understand how an online help is used, specifically in the case of software applications. The application is running on one window and the help file is open in another window. The user is probably just tabbing between the 2 open windows. Given that the user is already seeing the screen on one active window, does your guide really need to show static images of the same screen?

The obvious answer is no!

Screenshots, however, are not totally redundant. They are especially useful while explaining dynamic screens whose appearance changes based on user input – a configuration screen, for example.

Choose the Multiple Equipment option to enter details of several equipments together. The displayed screen looks as shown below. (Place a screenshot)

This example probably warrants a screenshot. Not only does the screenshot help the user verify that he has reached the correct screen, but it also provides context for the steps that ensue.

Intelligent Content for the Intelligent User

Not all users are the same with regard to their appetite for information; yet it is never a great idea to underestimate the intelligence of your reader. Making this distinction early on can help you write content that is relevant and useful to your specific user.

For example, while writing API documentation, you can do away with explanation of terms like Class, XML, SOAP, etc, unless specifically warranted (like in the case of glossaries or tutorials on those specific topics). This will help you keep your content crisp and to-the-point.

Here’s another example:

This is the help page for the User Information screen of an ecommerce website:

1. Enter your name in the Name Field.
2. Enter your email ID in the Email ID screen. (and so on)

Do you really need this explanation? I would instead prefer a one-liner that asks me to enter my personal particulars in the respective fields provided. I think I am intelligent enough to figure out that my name must go in the Name field. Aren’t most of us?

Logical Flow of Information

If the user sees screen/options 1, 2, and 3 in that order, your user guide MUST explain those steps in the same manner.

If you thought this is elementary, you’ll be surprised to know how often this basic rule is flouted. For example:

1. Select the page you want to print. 
2. Click Print. 
3. If you do not wish to generate a color print, choose Grayscale from the Options drop-down list before clicking Print.

Here’s an example where steps 1, 2, and 3 are explained in the order 1, 3, and 2. This sequence is confusing.

Here’s a better and straight forward way to explain the same sequence: 

1. Select the page you want to print. 
2. Choose Color from the Options drop-down list for a color print. Select Grayscale to generate a print in gray scale. 
3. Click Print.

Simple language

A technical writer colleague of mine once wrote the following in tutorial meant to explain business rules:

• YoungRule – Rule to be applied if the applicant is less than 25 years old
• MiddleAgedRule – Rule to be applied if the applicant is between 26 and 50 years old
• Codger – Rule to be applied if the applicant is more than 51 years old

A few weeks later one of our customers wrote a support mail pointing out that there was a mistake in our tutorial. The rule called “Codger” should perhaps read as “OldRule”.

He was right; but my colleague was not wrong either. A quick look at the dictionary will tell you that the word codger means old man.

But that’s the point – do you really want your reader to make a dash for the dictionary while reading your user guide?

Planning to start your own business? Decided to be your own boss, lay your own rules, and follow your passion? Here are some tips that helped me immensely when I decided to take the plunge:

1. Answer the obvious question first

• What do you want to do? Why?
• What are your differentiators? 
• Do your customers want it?

The last question is probably the most important and yet the most difficult to answer. Your customers are not going to spend money on what you are offering unless you give them what they are looking for. They need to see value in your product / service.

While at this, make sure to write down these answers rather than just visualizing them in your mind. Put them down on paper, and you’ll find yourself thinking with a lot more clarity.

2. Write a business plan

Once you have put down your business idea in words, start building on it to create a formal business plan – the more detailed, the better. Here are some important questions that you will be forced to answer in your business plan: 

• How much do you need to invest? Where will the money come from?
  In an ideal scenario, your investment must come from your savings. It’s really not such a great idea to borrow from family and friends unless they have a stake in your company. Remember to budget upfront for purchasing legal software and obtaining requisite government sanctions. 
• How will your product / service be priced?
  Pricing can be a very tricky topic. But as a domain expert, you’re probably best equipped to handle it. Beware of undercharging or over estimating your worth. Also, pricing is a dynamic parameter. So it might be worth creating different versions of your business plan based on different levels of pricing.

3. Is your family ready to take the plunge?

Your business is your baby. It is bound to change your family dynamics. Ensure that your family members know what to expect. Of course, they’ll support you.

4. Consider bringing in a partner.

Two is always better than one. Find someone who shares your passion and is as good or even better than you in your chosen domain. It would be best if your partner brings in skill sets that compliment yours. So if you are great at technology, you could choose a partner who is great at sales and marketing.

5. Make sure to comply with all statutory and legal requirements

You don’t have to become a legal expert to start your company – you just to need hire the experts. Consider hiring a competent chartered accountant to help you manage statutory requirements such as company registration, service tax registration, etc. Let a seasoned lawyer help you write out contracts, copyrights, and NDAs instead of trying your hands at it yourself.

6. Get more organized than ever before

Keep professional and personal expenses separate right from the start. Keep record of everything you do and every penny you spend. Put a simple yet scalable filing system in place for all papers relating to your business.

7. Draw out a detailed operational plan

Here again, the longer you spend planning, the easier it will be to implement.

• Private Limited Company or partnership?
• Work from a home office or hire office space?
• Employ people? If so how many and with what skillsets?
• Outsource work or work with consultants?

These poitners are far from exhaustive; but they are a good way to get started…

There nothing more enjoyable than learning from your children. My three-year-old is always teaching me valuable lessons on anger management, time management, and leading a disciplined life in general. I recently realized that observing my child closely can help me learn a lesson or two about my professional customers. Here’s what I found:

You have to give them what THEY want

My child repeated his request for a “blue car” for weeks until I got him one. No, the red and black ones he already had would just not do! One of my customers would not budge until I placed a certain screenshot in a user guide even though it was obviously unnecessary under the given circumstance. See the parallel?

Negotiation is the key

You certainly can’t get anywhere without negotiating with your child – “If you want to paint this picture without messing it up, you have to let me help you”. Well, haven’t we all spent time negotiating with customers who have unreasonable expectations? – “If you want great documentation, you simply have to give me more time.”

Packaging is important

Your child is always attracted towards toys that are nicely wrapped in glittering paper. Same is the case with your customer. Packaging your content is important. You must give due importance to the fonts, colors, background images, and other style elements. Beware of jarring colors and bulky images.

Give them more than they are expecting

Sometimes I give my child a bonus toy for his good behavior. It’s just amazing to see the happiness on his face. It makes my day. With customers too, you can delight them by doing more than what you are expected to do. A delighted customer is an asset for life. They’ll always return to you for their work.

Don’t take them for a ride

If you expect your child to be truthful, you have to lead the way by being a role model. If you lie to your child, he will only follow your example. With customers too, it’s very, very important to be truthful and transparent. If you think you can bill your customer for hours that you have not really spent on their work, you’re asking for trouble. Act respectably and you will get respect and recurring business in return.

A technical writer’s work is only part writing. To do this part of your job well, there are several other things you must do continuously:

1. Talk to SMEs
   The best source of information about the product you are writing about is subject matter experts (SMEs). Talk to them often using both the formal and informal channels. Sometimes, you’re likely to learn a lot more about the product talking to a developer over coffee than during a closed-door meeting with the entire team. It’s not unusual to find SMEs who are great at their work but don’t fare very well in the communications department. Put such people at ease and don’t intimidate them with your superior communication skills. Try using their local language to make them more comfortable – to your surprise, you’ll find them giving you a lot more information and insight than you could have ever imagined.
2. Keep your ears open 
   Join technical team meetings, status meetings, and even customer demos if possible, and keep your ears open. You will learn a lot about the product’s capabilities, limitations, and customer use cases, which in turn can help you provide richer and more relevant information in your user guides.
3. Become the user – try things out first hand
   Get your hands dirty and do all that you want to tell your customer to do. It may be slightly time consuming, but it will be worth the effort in the long run. Having done it all yourself, you will know exactly what to write about and how to write it best. This approach will also help you sequence flow of information logically.
4. Don’t try too hard to understand everything
   While is good to try your hand at the product yourself, it is a common mistake to try an internalize everything. This is particularly relevant while writing API documentation for example. Remember that you are not the subject matter expert and hence you need not understand everything that’s going on. You need to know “what” happens and in many cases “why it happens”. But you really don’t need to know everything about “how it happens”.
5. Become a proxy quality and testing personnel
   In most organizations, documentation runs in parallel with development. So as you keep writing, make sure to identify and report bugs, inconsistencies, and errors. These things may not be part of your job description; but if you ignore them, your dissatisfied customer will crib them later. Worse, he will hold you responsible for not warning him in advance about them in your documentation.
6. Help identify usability issues
   As one of the first users of the software, you can help catch, if not all, but at least the more obvious usability issues. Many companies now treat their technical writers as part of their extended user experience group. So make sure to contribute your bit to make your product user-friendly. This will indirectly reduce your work load – products that are easy to use need lesser documentation and support.
7. Identify topics with “special needs”
   Make a note of complex topics that users might need additional help with. For example, identify topics that are probably best explained in the form of a video. There are other obvious examples, like ensuring that installation guides are not bundled with the software – users must be able to read it before or while installation. So you can create a special installation guide that is available online.

1. Define your audience

Anybody from anywhere could stumble upon your writing. But only those who are interested in the subject will go on to read what you’ve got to say. So your audience is not the entire superset of internet browsers, but is, in fact, a very small subset of interested people who are looking for information online. So stick to the subject and don’t try to add unrelated information just to humor random visitors to your webpage.

2. Search Engines also are your audience

Search Engines are your “audience” too. If they don’t find you, your target audience is not likely to find you either. So make sure to play to the gallery by adding relevant tags and titles to your HTML pages and embedding relevant keywords into your content.

3. Say what’s most important first

A typical online reader will quickly scan a webpage to see if it “seems” to have the content she is looking for. If you don’t capture your reader’s attention in the first couple of seconds, you probably will not get a second chance. So make sure to use catchy and, of course, relevant titles and headers to create the right first impression. Say what’s most important first to keep the reader interested in your write up.

4. Create magic with links

On the web, less is more. While readers might be willing to spend hours, even days, reading a book, online readers will not spend even a fraction of that time. You can keep your online articles short and simple and yet pack loads of information into them by using links. Use hyperlinks to break up content into chunks and help your reader systematically navigate through all the information you have to provide.

5. Focus on readability

Reading online is often far more strenuous than reading printed matter. Use fonts and colors that are suited for online reading. Break content into multiple paragraphs to reduce clutter and improve readability.

6. Talk to your reader

Talking to your reader is the best way to get them involved. Use short sentences, simple language, and a conversational tone whenever possible. Your reader would rather look for information elsewhere on the web than make a dash for the dictionary to understand what you’ve written. Use active voice and talk to your readers in first person.

7. Roll out great content without reinventing the wheel

While working on the web, it is always a good strategy to reuse what’s already available out there. You can provide links to related articles so you can stick to saying what you want to say without laying an elaborate foundation for the topic; you can make somebody else’s article the starting point for yours to provide the right context; you could do away with lengthy explanations of certain terminology by simply providing a link to another webpage that does the job in detail. So you don’t have to reinvent the wheel. Do your homework (research) well and work smart.