Posted on

Configuration Guides: How To Document Parameters

Configuration-Guides-how-To-Document-Parameters

So, you want to document the parameters for your new Configuration Management Guide.

Where do you start?

Here’s a checklist of what you need to capture when documenting parameters in technical documentation:

Parameter Name

Specify the name of the parameter with consideration to case sensitive naming conventions. Likewise, use the correct format and styling when entering parameters to your documents.

configuration-management-plan-template

Download the Configuration Guide Template here.

 

Location

Specify where in the configuration file that parameter is located. For example, is it part of a specific parameter set or a section of common parameter setting?

For example: This table describes the Log parameters of the Common section:

In this case, the Log parameters are part of a common set of parameters used by the service, server, or application.

Purpose

Describe the benefit to the user when this parameter is configured. Outline what it enables them to achieve and, if necessary, any downstream impacts. For example, if you turn on this option, other options are made unavailable.

However, make sure you provide enough information for the user to understand the parameter’s purpose and also how this impacts other parts of the system, for example:

Defines a locally stored backup license file. This provides protection against interruptions occurring if the connection to the license server is lost.

Prerequisites

Describe if this parameters activities are impacted by other parameter settings, for example:

Defines if a new log file is created at the time specified by the Time parameter or when the current log file reaches the size specified by the Size parameter.

A second example is if the settings are enabled if another setting is set to a specific setting in a different parameter, for example:

Defines if messages are filtered according to the Filters parameter if the Verbosity level is set to comm.

Options

Describe the parameter options is the settings are turned on or off. For example, state which options are available and then describe the settings.

  • True – describe what occurs if the True setting is selected, for example, enables statistics support.
  • False – describe what occurs if the False setting is selected, for example, disable statistics support.

Default value

Some parameters come with a default value, for example, 0, 1, Yes or No. Specify the default value so it’s clear to the reader if they need to change the setting or leave it in its default status.

Use the following phrasing: This is the default value.

Impact

Highlight if this setting impacts other parts of the system, for example, it overrides another parameter’s settings, disables another feature, or impacts the performance of the system.

Related documentation

If necessary, direct the reader to other sources of information which may help them understand the parameter a little better. For example, if it impacts another module or system.

Mandatory

State if the parameter is mandatory.

Note – identify any recommended settings or values which must be set for the parameter to function correctly, for example:

The value of the parameter must match the value specified for the Metrics parameter.

Minimum Settings

A second example is if the parameter must be set to a specific setting, for example:

The value of the parameter must be equal or greater than the value of the TimePeriod parameter.

Multiple values

For some parameters, you can specify a default value, for example, 1000 but also highlight other possible settings, for example:

The default value is 1000. The following values can also be defined:

  • 0 — no data is sent to the server.
  • 1 — data is sent to the server as soon as it is collected. This value reduces performance.

How to document parameters

Describe the parameter settings as follows:

The first sentence describes the purpose of the parameter in a single sentence.

The second sentence describes the available options and highlights the default settings, for example:

The following options are available:

  • True — enables statistics support
  • False — disables statistics support. This is the default value.

State if the parameter is mandatory. Use the following phrasing:

This is a mandatory parameter.

Summary

The skill in documenting parameters in technical documentation is to describe both the parameter and how it affects other settings, modules, or applications.

This means, as a technical writer, you need to understand how it connects to other parts of the system.

Without this knowledge, your documentation may be adequate but not help the reader understand its impact on other products.

PSDownload the Configuration Guide Template here.

Posted on

How to Find Broken Links in Madcap Flare

madcap-flare-broken-links

Tired of all those pesky broken links in your WebHelp projects? Wish they’d go away? Well now you can!

If you use MadCap Flare to create your web help, you can run a broken link checker.

It’s not perfect. But it will catch most dead links, which is a start.

Finding broken links in Madcap Flare

To find broken links:

  1. Click the Project Analysis
  2. Select Broken Links from the drop-down list.

madcap-flare-broken-links

The results are displayed in the Broken Links window.

 

Posted on

Madcap Flare: How to add The Mark of The Web

madcap-flare-mark-of-the-web

Using Madcap Flare for WebHelp?

If you have problems getting Internet Explorer to run web help pages, added ‘Mark of the Web’ to your WebHelp files.

Madcap Flare: How to add Mark of the Web

You can add the Mark of the Web to HTML files so they run locally in Internet Explorer.

  1. In Project Organizer, click Targets, then open your target, for example, HTML5.
  2. In the Tag Editor, click Advanced.
  3. Select the Insert Mark of the Web check box.

PS – Join our Technical Writer’s page on Facebook.

 

Posted on

How much can you make as a technical writer?

Right now, the average aalary of Technical Writing Job in the USD (May 13, 2015) is…

low end 45k

middle earners 90k

high end        135k

Here’s a fuller breakdown:

Engineering Technical Writer $54,000
IT Report Writer $69,000
IT Technical Writer $74,000
Senior Proposal Writer $80,000
Technical Proposal Writer $69,000
Technical Writer $123,000
Technical Writer Contract $61,000
Technical Writer Editor $64,000
Technical Writer Illustrator $39,000
Technical Writer Scientific $61,000
Technical Writer Senior $64,000

You can get the full details at: http://www.indeed.com/salary/Technical-Writer.html

Posted on

Over 50? Would a career in technical writing suit you?

If you have good writing skills, enjoy technology, and like to help others understand how things work, then a career as a technical writer might suit you.

1.0      Technical writer work/life balance

Technical writing has been very good to me.

It’s allowed me to work in China, London, San Francisco, and Amsterdam.

Most of the time I work from home even when I work full time for clients.

Unlike other jobs where you need to be in the office every day, as a tech writer you can work from home quite easily. All is you need is a decent web connection and the ability to manage your own time.

I’m sure you can do both.

1.1      Technical writing salary

The pay is good, too. Look at these rates for full-time technical writers in the US.

If you work as a freelancer, you should be able to double these figures.

According to the BLS, the annual salary for technical writer ranges from 41k to 108k.

Annual Wage $41,450 $53,080 $69,030 $88,230 $108,460

The average hourly rate for technical writing is as follows

Hourly Wage $19.93 $25.52 $33.19 $42.42 $52.14

http://www.bls.gov/oes/current/oes273042.htm

1.2      The future of technical writing

Going forward, as they say, the future of technical writing looks bright. Government statistics show the demand is up.

Of course, the tools, software, and products change. Many companies now outsource to India, Singapore and other low cost centers. That’s to be expected. Outsourcing affects most every industry.

Actually, later in this course, I’ll show you how to use outsourcing to your advantage.

1.3      Demand for technical writers

The thing is: there will always be a demand for skilled writers.

But even more important: there will always be a demand for reliable writers.

The BLS expects the employment of technical writers to increase by 17% from 2010 to 2020.

This compares to 14% for all jobs, and 13% for all media and communications occupations.

What’s driving this?

The expansion of scientific and technical products, and the increase of web-based product support will fuel the demand.

Professional, scientific and technical services firms will continue to be a source of new jobs because many companies are outsourcing their technical documentation needs. Job opportunities will be best for those with strong technical skills.

1.4      What education do you need to be a technical writer

I have no degree, diploma, or certification in technical writing.

But I’m very reliable.

More reliable than other writers who are way more qualified than I am, but possibly less motivated.

Next week, I’ll explain how I got my first technical writing job. Maybe the approach I took will help you.

1.5      Is technical writing really for you?

There are different ways to develop a career in technical writing.

Yes, you do need to know how to write.

Yes, you do need to know the authoring tools (but that’s less important.)

And, Yes, you do need to be super reliable.

Why?

Technical writing is a service career.

You’re developing products that others need – now!

It needs to be accurate. It needs to be easy to understand. It needs to be ready on time.

Many writers get the first two right, but not the third.

So, don’t underestimate how important it is to be reliable.

Even if you don’t have a degree, even if you are not a native English speaker, I’m certain you can develop a successful technical writing career.

But you have to be willing to make the effort.

Sound interesting?

Sign up for the newsletter. Let’s get started.

Posted on

How to find technical writing work on LinkedIn

How much technical writing work have you got from LinkedIn? Ever?

Let’s look at how to get more work, especially contract work, from LinkedIn.

If you’re doing some of the following, let’s stop and think a minute.

  • Are you in more than ten groups?
  • Do you post to your own profile only but not to groups?
  • Does your profile page look like a CV?
  • Are you on SlideShare?
  • Do people ask for you help?

If you answered Yes to more than two, don’t worry you’re in the boat as most people.

If the boat is not going where you want it to, here’s what to do.

1. On your LinkedIn groups

  • Contribute to 10 groups only. More than that and you lose focus.
  • Leave groups with low engagement. This video shows how to find the most useful groups on Linkedin.
  • Don’t waste time posting to your own profile. Spend your time in groups instead.
  • Aim to be a top contributor on your LinkedIn group. This video shows you how. A ‘top contributor’ is seen as a type of expert. That’s what you want to be, right?
  • Study the threads that have the most comments. Write a LinkedIn post about this. Name check people. Drop them a line and tell them that you’ve recommended and shared what they said. Most will share your article.

Then:

  • Ask questions that create conversations.
  • Ask questions that involve others.
  • Ask questions that show you’re not selling, you’re helping.

Remember, everyone else is selling.

Of course, you’re selling too. But, it’s more subtle.

You’re saying, ‘I’m here to help. Ask me anything.’

2. On your LinkedIn profile page:

  • Create a ten page white paper. Upload it and share. Make the cover page stand out. Don’t use the default page on MS Word. Make it zing!
  • Create a PowerPoint presentation, convert to PDF, and upload to SlideShare. LinkedIn owns SlideShare. Upload it and embed it into your LinkedIn profile.
  • Delete the default background image. Find something with a bit more energy. Examine the profile pages of LinkedIn stars for inspiration.
  • See the difference it makes?

3. On your LinkedIn blog page:

  • Write 10 x 300 word articles.
  • Don’t write about the tools, fads, social media, or Better Call Saul.
  • Focus on two things: making money and saving money.
  • Connect it to what you do as a technical writer. That’s your angle.

4. Summary

Study LinkedIn. Get as many ebooks as you can find. Always look for ways to get more from it.

Your aim is to build credibility. Do exceptional things that make you stand out.

Give. Be seen to be generous. Help. Avoid the haters.

Look for ways to help others. Then the emails will start to come in.

PS – when they do, be ready to respond.

Posted on

Do you have a technical writer’s personality?

Considering a career as a technical writer?

Want to know what kind of people enjoy technical writing the most? Would it suit your personality?

Is being introverted an advantage? Can jovial types make it as tech writers?

Yes and Yes.

Crag on Helpscribe makes the point that, “Personality can also have a strong influence on your ability to perform technical writing tasks. For example, a highly social writer will have a much easier time interviewing SMEs and contributing during meetings. A less social writer may have an easier time surviving as the sole writer on a project or staying focused and productive for long periods of time.”

While there is no one personality type for technical writing, after working in this field for twenty-three years, I can see some people do better than others. A lot has to do with what technical writers do every day, which isn’t all writing, by the way. A surprise for most new writers.

My typical technical writer’s day

If I look at my day, it’s:

  • Mostly spent alone, which I enjoy.
  • Chasing people for information by email. Many don’t have English at their first language.
  • Re-writing their text.
  • Organizing document reviews usually by email
  • Skype interviews with Dev
  • Technical tasks such as fixing the online help system
  • Developing documentation plans
  • Writing technical material
  • Attended meetings in person, over the phone/web

As you can see, there’s a mix of tasks.

I only spend 3 days a week actually writing. The other two are in meetings, workshops, reporting, email and other communication tasks.

  • Three days working alone
  • Two days working with others.

Even though I’m in a busy office, I tend to keep my head down and get through the work.

1.0      Technical writing personality traits

If you look at my typical technical writing day, you can see that I’ll need different skills. Some come naturally to me, such as enjoying working alone on technical things, others less so, such as workshops, which I often find talking shops – lots of chatter, no real benefit.

But let’s look at the personality traits.

1.1      Introverted writers

Many writers, in all fields, tend to be introverts. They enjoy the pleasure of being left alone to work on something, especially something with an intellectual angle, that gives them satisfaction. I can spend all day working alone and be as happy as a sandboy. But this has it’s downsides…

1.2      Extroverted writers

Surprisingly, many of the most successful writers, especially team leads, as very outgoing and social creatures. You can’t have a team of five introverts. You need a leader, someone who can motivate (gently bully J) the technical writers to hit the deadline.

From that angle, extroverts can have very successful careers in technical writing. Positions that require project management skills, working with Development, hiring/firing, are also need in tech pubs.

It’s also worth noting that the term ‘technical writing’ is misleading. A lot of your time as a technical writer is spend using developing content for web publishing, creating online help, and generating content for omni channels.

This is probably the big surprise for junior and new technical writers – how much time is spend on non-technical writing tasks.

1.3      Details

Every line I write is reviewed by another technical writer. Every line. Editing skills are crucial.

In some ways, I’m a better editor than writer. More on this in later posts.

As a technical writer, you can expect to spend many hours editing text.

You’ll get this text from emails, wiki pages, intranets, white boards and even on scraps of paper. You also have to edit your own work. This means you need to put on an Editor’s hat every week (or day) and not resent having to fix others text. A lot of technical writing is refining text.

I enjoy it. For me, it’s playing with works. How can I improve this line of text?

1.4      Patience

The trend towards outsourcing means that for many developers English isn’t their first language.

I mention this as you do need to be patient and understanding as you’ll often get text, for example, for release notes, which may be very difficult to understand. Your job is to make sense of this. This means refining the text and, where necessary, working with the developer to understand the issue better. It takes practice. Some technical writers struggle with this. They just want to write. But, your job isn’t just to write it’s to re-write what others have written.

So as well as writing and editing and reviewing you’re also translating. Again, I enjoy it. Not everyone does. Some resent it and feel it’s beneath them.

1.5      Interviewing skills

Let’s say you’re developing a new cutting edge product. Or you’ve joined a new company but have very little experience of their industry. You need to document it. Where do you start? You can get so far by reading white papers, technical guides, and blogs. At some point you need to talk to Developers, Business Analysts, and Project Owners.

This usually involves organizing workshops, one to one interviews, and small roundtables where you discuss the product, learn how it works, so you can start to write the conceptual materials. Good interviewing skills help you gather this material, develop a better understanding of the product, and build bridges with other teams.  Interviewing skills are, in my opinion, the most underrated skills in technical writing.

1.6      Determination

One of the biggest shocks for new technical writers is the amount of hunting they have to do to find information. They expect it to be there, wherever ‘there’ is. However, in most technical publication departments you need to be proactive and track down content. It could be on the web, on intranets, on wikis or, as if often the case, in someone’s head. But you have to get it. How you do it…

1.7      Summary

As you can see, there is no ‘one size fits all’ in technical writing. For example, Introverted and Extroverted writers both have their place. Both can play to their strengths and carve out careers that work for them. Saying that, you must love the details, have oodles of patience, Interviewing skills really do help and be determined.

Posted on

How to find technical writing work using Quora

Are you using Quora to find technical writing work?

Maybe you’ve never heard of Quora.

Here’s how it works.

Think of it as a deluxe ‘Question and Answer’ site focused on the business community.

A lot of influential people are there. It has almost no spam or nasty comments.

If you want to develop your business, Quora is an effective way to demonstrate your expertise and generate leads.

Like the X-Factor, it uses a voting system. The better your answer, the more votes it gets, the higher it ranks, the more links you get, and the more…

Tip – You can link out to other articles, which is what I often (though not always) do.

Here’s my answer to: How can I become a better writer.

On your Quora groups

Let’s look at how to establish yourself (your personal brand) on Quora

Join 10 groups. Make sure they complement your business goals.

Avoid distractions. More than 10 and you lose focus.

Ignore groups with low engagement.

Aim to be a top contributor on your Quora group. To do this, write the longest article you can. Twice as long as others in the group. Even if your article isn’t great, people tend to upvote long posts. I think they appreciate the effort. It looks epic!

Study discussions that have the most comments. See what makes the top post stand out. Make notes.

Write a Quora post about this. Write a Quora post that deliberately takes the opposite point of view. The contrarian angle often works as it evokes a response in others and they feel compelled to respond.

Where possible, include others by recommending their sites, books, or other works. Connecting with others (especially those who have a larger network) raises your profile and gets you on their radar.

When answering questions:

  1. Be selective. Answer one question a night.
  2. Provide more detail than anyone else.
  3. Use the inverted pyramid style when writing.
  4. Use lots of white space, short sentences, and bullet lists. Write to be scanned.
  5. Link to sites you recommend but not affiliates.
  6. Format and style your answer to stand out. Don’t just copy and paste from MS Word.
  7. Add images, slides, and videos.
  8. Aim to write the standout article.

On your Quora profile page

Use a nice, professional headshot.

Write the bio in a conversational style. Talk about how you’ve helped others in the past and look forward to helping others. Be open. Encourage the reader to learn more about you.

Don’t link to your blog homepage.

Instead, link to your About page. That’s where they can learn more about you. Include an email subscription form on your About page in two places, in the side bar and at the end of the page.

On your Quora blog page

You can create your own blog page on Quora. One of mine is at klariti.quora.com

Use this to repurpose content from your blog. I usually sprinkle in a few hundred new words to tailor it to the Quora readers.

Write original content related to the questions you’re answering.

Write ‘original’ content using the material from the question you answered. Avoid copy and pasting. Instead, write a short intro paragraph to put it in context, then a summary to wrap it up.

  • Write frequently. This helps develop your voice.
  • Watch this video on how to create a writing framework.
  • Find an interesting angle.
  • Write 10 x 250 word articles.
  • Don’t write about fads, Apple, Seth Godin… the usual.
  • Focus on potential customers: how can you help them save and make money.
  • Connect it to what you do as a technical writer.

Your Quora to do list

  • Study Quora.
  • Get the app.
  • Observe how others use it.
  • Scan posts during the day. Get a feel for what works.
  • Your aim is to build credibility.
  • Write exceptional answers that make you stand out.

Summary

Before you start. Have your LinkedIn profile, blog, and business web site ready.

When they arrive, offer them ebooks, reports, or checklists. Don’t let them leave empty handed.

If you can persuade them to join your email newsletter, even better.

More next week.

Posted on

How I use Twitter to find technical writing work

KB from London heard that I use Twitter to find work.

Like many of us, she thought Twitter was a waste of time and ignored it. Maybe we can change her mind.

How I use Twitter to find technical writing work

Here’s how I use it.

Create a twitter account for your business. Add a keyword into the title, for example, if you’re an accountant, call your twitter account @Accounting140 – accountancy tips in 140 characters.

Add links to your website in the profile. Add your business logo. It has to look professional. Go to oDesk and spend $100 on a nice new logo and design.

Learn how to create Twitter lists.

  • Create a list for people who have a lot of influence in your industry.
  • Create a list for people of your competitors.
  • Create a list for people who are generous, who retweet, and who are willing to help you if you help them.
  • Keep these lists private.

Next

Follow chats. Do a Google search for twitter chats related to your industry. Add the date to your calendar.

Ask questions. This works very well. Others are promoting themselves too hard. Instead, you ask questions about your line of business and help others.

Add one hashtag to every post/question. Don’t over do it.

Next

Do Searches. Here’s an example. Type the following into Twitter.

Excel ?

This returns tweets related to Excel from people with questions.

Question  = problems.

Change the text.

Excel pivot ?

Excel export ?

Excel freeze ?

Then answer these questions. If you have a site, send them there.

This works very well and takes little effort.

If you do this every day for ten minutes:

People start to follow you.

People add your account to their, usually public, lists.

They start asking you questions.

You’re seen as an expert. You can encourage them to visit your site, see your services, and connect.

Ten minutes a day. Try it.

Posted on

C# Namespace Guidelines

Let’s create some guidelines for documenting .Net Namespace.

For example, let’s look at the System.Collections Namespace. What do we notice?

Namespace – define the namespace using the following convention: System.Collections Namespace

Purpose – describe the purpose of the namespace, for example:

crone-park (33)

 

The System.Collections namespace contains interfaces and classes that define various collections of objects, such as lists, queues, bit arrays, hash tables and dictionaries.

Classes

We then identify the classes related to the namespace. For each, we identify it and describe its purpose. Use the correct case when documenting the
classes.

Note: it’s ArrayList, not Arraylist or arrayList.

Class Description

ArrayList – implements the IList interface using an array whose size is dynamically increased as required. Note how IList is spelt. Both the I for
Interface and L for List are capitalized.

BitArray – manages a compact array of bit values, which are represented as Booleans. True indicates that the bit is on (1). False indicates the bit is off
(0).

CaseInsensitiveComparer – compares two objects for equivalence, ignoring the case of strings.

CaseInsensitiveHashCodeProvider – Obsolete.

Structures

Next, identify the structure related to the namespace.

Structure Description

Dictionary Entry Defines a dictionary key/value pair that can be set or retrieved.

Interfaces

For interfaces, note the casing for IDictionaryEnumerator. I for Interface and D for Dictionary and E for Enumerator are capitalized.

Interface Description

ICollection – Defines size, enumerators, and synchronization methods for all nongeneric collections.

IComparer – Exposes a method that compares two objects.

IDictionary – Represents a nongeneric collection of key/value pairs.

IDictionaryEnumerator – Enumerates the elements of a nongeneric dictionary.

Use verb constructions to describe the purpose of each interface.

Posted on

What is a Statement in C#?

In C#, statements express the actions that a program takes.

Common actions include

  • Declaring variables
  • Assigning values
  • Calling methods
  • Looping through collections
  • Branching to another block of code

crone-park (35)

The order in which statements are executed in a program is called the

  • flow of control or
  • flow of execution.

This may vary every time that a program is run, depending on how the program reacts to input that it receives at run time.

A statement consist of one of the following:

  • Single line of code that ends in a semicolon or
  • Series of single-line statements in a block

A statement block is enclosed in {} brackets and can contain nested blocks.

 

 

Posted on

How to Write Error Messages: Faster, Stronger, Better

error-messages-how-to-write

Blame the cat, TV, or the neighbors if you want. The thing is: stuff happens. When it does, you need some way to fix it, pronto. Aren’t  I right?

This is where error messages can save you bacon.

No one thinks of writing an error message guide until it’s too late.

So, I’m telling you now, grasshopper: Get cracking on that Error Message Guide before it happens.

Why oh why do I need an Error Message Guide?

Here’s the skinny…

These guidelines will help you write error messages that are easy to update and useful for customers.

If you think about it, error messages are the first line of customer support. If written poorly, error messages increase technical support costs. They also frustrate customers, lose sales, and reflects poorly on your software, app, or website.

Errors are a fact of life in software development.

Every site has 404 errors.

Every software has bugs, known issues, and glitches.

Once we accept that, we can begin to help customers use our software, and help them get around the issues they encounter. If you think of it like that, the issue isn’t the error message it is our attitude to creating error messages.

Ok, let’s assume that we want to create really helpful error message, you know, the type we’d like to see if we got lost on a website, using an app, or trying to fill a form on an application.

What’s the purpose of an error message?

A well-written error message tells you, the user, the following:

  • What has happened
  • Why has it occurred
  • How it impacts you and
  • What you, the user, can do to prevent it happening again?

The error message must include enough information to solve the problem.

What is an error message?

An error message describes a problem that stop a user or system from completing a task.

What types of error messages are there?

There are four main types:

  • Errors
  • Confirmations
  • Warnings
  • Notifications.

If a message has different audiences, create separate text for users, administrators, and developers.

Why do we use the word error in error messages?

Isn’t part of the problem the word error? It’s assumed the user made the error. If you think about it, the problem is often the software, for example, it wasn’t designed to accommodate unexpected behavior.

If we see it like this, the error is on the side of the developers. If that’s the case, you don’t want to blame the user just because they entered 05122020 instead of 12052020 when entering a date. I tend to use 0512 whereas maybe you use 1205. Good software anticipates this and, where necessary, provides the direction the user needs.

Error Message Guidelines

Error messages should address the following, though not in this order:

  • Be constructive: tell me what needs to be done!
  • Be as specific and precise as possible.
  • Educate. We only read tech docs as a last resort. Knowing this, write error messages that educate and teach the user how to use the application. Nice examples always help.
  • Indicate that something has gone wrong, but then help the user understand what to do next.
  • Offer different levels of messages, some for beginners, others for advanced.
  • Provide direction. Instead of saying, “none in stock,” tell them how to find out when it’s back in stock. Is there some page, app, or contact number that can help them with this?
  • Save as much as the user’s work as possible. For example, allow users to correct errors instead of having to start from scratch.
  • Use a positive tone: avoid condemnation.
  • Use consistent grammar, terminology, and abbreviations.
  • Use consistent visual formats and placement.
  • Use terminology your audience will understand.
  • Use Plain English – plain in the sense that it is concise, accurate, and avoid any unnecessary words.
  • Use user-centered phrasing.

Error Message Mistakes To Avoid

Try to avoid the following:

  • Blame. Maybe the user did the wrong thing, for example, entered text into a field meant for numbers, so technically it is their fault. However, instead of saying this is wrong, bad, or illegal, state that this field only takes numbers and encourage them to try again.
  • Cryptic numbers. Error message 724 for example means nothing to the user. The developer may know what this means but she should refine the error messages to help the user, not her own team or others debugging the application.
  • Generic ‘catch-all’ messages. Determine the cause of the error and create an appropriate error message.
  • Jargon. What does syntax error mean?
  • Jokes.
  • Negative phrasing, such as wrong, bad, invalid, and illegal.
  • Red to indicate an error. Red looks terrible. It sends a warning that something is very wrong. Avoid where possible. There is an exception though. If the user is about to do something that could have DRASTIC consequences, then consider using red, for example, if they are about to format their hard disk and lose all data. Let them know this immediately and make it so obvious they can’t miss the warning sign.
  • Slang or abbreviations.
  • The word error in the title bar.
  • Anthropomorphize. Do not imply that the software has feelings or thoughts.
  • Terms that may be offensive in certain cultures.

How To Improve Error Messages

Ask yourself: how can I help the user solve their problem as painlessly as possibly?

One problem with most error messages is that while they indicate that an error has occurred, they don’t mention what steps the user should take to a) avoid this happening again and b) resolve the current issue.

  • Rewrite temporary error messages written during testing. Examples of these might refer to null pointer errors or issues with the class, objects, or interfaces in the code. None of this should be displayed to users when the product is finally released.
  • Many error message leave the user in a type of limbo unsure what caused the issue and, for example, how to recover data they may have lost if the system crashed.
  • If possible, create links to FAQ pages where users can learn more, download the necessary patches, or contact support.
  • Get the technical writer to write and enhance the messages. If you’ve no tech writers on your team, assign them to the person with the best writing skills.

How to Write Error Messages

  • Create a spreadsheet, for example, using Google Spreadsheets so you can share it online.
  • Add columns for the error message and the root cause.
  • Give each error a number so you can track them.
  • Establish an error message quality-control team.
  • Find best practices. Share with the team.
  • Create simple to follow writing guidelines for the error messages. Share examples.
  • Include error and information messages in the design phase.
  • Place the messages under source control.
  • Review messages during the development lifecycle.
  • Attempt to eliminate the need for messages.
  • Carry out acceptance tests.
  • Review and revise messages periodically.

Best Practices

You don’t need to use all of these all of the time, but they’re nice to refer to:

  • Avoid the word “bad”. Use more descriptive terms to tell the user what is wrong. For example, avoid messages such as “Bad size”. Instead, tell the user what criteria to use when specifying a size.
  • Avoid the word “please”. It can be interpreted to mean that a required action is optional.
  • Avoid UPPERCASE text and exclamation points.
  • Explain the solution to the problem. If it has more than one step, link to a Help page the explains the task in detail.
  • Insert descriptors before a term to clarify the meaning of the sentence. For example, “Specify ID when Detect is set to No.” should be changed to “Specify the ID parameter if the Detect option is set to No.”
  • State the problem in plain English. Explain what caused the problem. Use complete sentences.
  • Use active voice if possible.
  • Use passive voice to describe the error condition.
  • Use the Cancel button to stop an operation and close the message box.
  • Use the Close button to close a message box.
  • Use the Details button to provide more information about the root cause.
  • Use the Help button to provide more information about the solution.
  • Use the present tense to describe the conditions that caused the problem.
  • Write critical errors to an event log.
  • Write separate error messages for each known issue.

Microsoft’s Guidelines for Error Messages

When you write messages, follow these guidelines:

  • Avoid vague wording. Give specific names and locations of the objects involved.
  • Avoid “please.” It can be interpreted to mean that a required action is optional.
  • Do not refer to implementation details that are invisible to the user. For example, do not refer to the names of functions or objects in the program.
  • Avoid phrasing that will seem silly to the user, such as “unexpected error.”
  • Avoid using placeholder variables in the middle of a message. They are very hard to localize.

Correct

The name of the object file conflicts with that of another program in the project. File name: %s

Works did not find a match for this term.

Incorrect

You have named the object file with the name of another program in the project. File name: %s

The term you typed does not appear in this Works file.

Source: Manual of Style for Technical Publications

Example of IBM Software Error Messages

The following is an example of how IBM writes error messages. Notice the words and phrasing as well as how the alert categories are explained.

Error Message

There is no value specified for the User ID.

Explanation

You must specify a value for the user ID.

Alert Category

Similar events are grouped in categories. The alert category is in the following format:

Severity – device component

Severity is one of the following severity levels:

  • Critical: A key component in the server is no longer functioning.
  • Warning: The event might progress to a critical level.
  • System: The event is the result of a system error or a configuration change.

Sample Oracle Error Messages

The following is an example of how Oracle writes error messages.

Notice the format of the error message:

  • ORA-00058 – error number for tracking
  • DB_BLOCK_SIZE must be string to mount this database (not string) – description of error message
  • Cause: what caused the error to occur
  • Potential reasons: note the use of the word potential in the following example.
  • Action: what steps need to be taken

For example:

Cause: The value of the DB_BLOCK_SIZE initialization parameter used to start this database does not match the value used when that database was created.

Potential reasons for this mismatch are:

  • Mounting the wrong database
  • Using the wrong initialization parameter file
  • The value of the db_block_size parameter was changed

Action: For one of the above causes, either:

Mount the correct database

Use the correct initialization parameter file

Correct the value of the DB_BLOCK_SIZE parameter

Sample Microsoft Windows Error Messages

The following is an example of error messages for Microsoft Windows XP:

When you try to install a program that uses the Windows Installer in Microsoft Windows XP, the program does not install, and you may receive an error message that is similar to one of the following error messages:

  • The Windows Installer service could not be accessed. Contact your support personnel to verify that the Windows Installer service is properly registered.
  • The Windows Installer service failed to start. Contact your support personnel.

Internal Error

This issue may occur when the Windows Installer files are missing or damaged.

To resolve this issue, use one or more of the following methods in the order that they are listed.

It then describes three different methods to resolve the issue.

Method 1: Reregister the Windows Installer

  • Quit all Windows programs.
  • Click Start, click Run, type msiexec /unregister in the Open box, and then click OK.
  • Click Start, click Run, type msiexec /regserver in the Open box, and then click OK.
  • Restart your computer.

Method 2: Remove the Windows Installer files

  • Quit all Windows programs.
  • Click Start, click Run, type msiexec /unregister in the Open box, and then click OK.
  • In Windows Explorer, rename the following files in the %systemroot%\System32 folder:
    • Msi.dll
    • Msihnd.dll
    • Msiexec.exe

Note: If you cannot rename these files, try to rename the files at a command prompt. To start a command prompt, click Start, click Run, type cmd in the Open box, and then click OK.

  • Restart Windows XP.

Method 3: Restart Windows XP in Safe Mode

  • Restart Windows XP in Safe Mode, and then retry Method 1 and Method 2 in the order that they are listed.

Finally, it provides more information about how to restart Windows XP in Safe Mode, by suggesting you read the following article number to view the article in the Microsoft Knowledge Base: 316434 How to perform advanced clean-boot troubleshooting in Windows XP

Sample Google Chrome Errors Messages and Warnings

The following is an example of error messages from Google Chrome. Note the tone, language, and phrasing.

You might see an error message when a download fails.

It will show up on the download bar at the bottom of your browser screen or in the download page that opens.

Note the use of the phrase ‘show up’ instead of display or appear. Likewise, the use of download in lowercase instead of uppercase.

If something you’re about to download could cause problems, Chrome also warns you.

Common warnings for harmful or unwanted programs

Certain downloads can cause viruses, leak your private data, change your browser and computer settings, or add unwanted extensions or toolbars to your browser.

Chrome warns you of potential issues:

Malicious download warning: You tried downloading malware.

Uncommon download warning: You tried downloading an unfamiliar and potentially dangerous piece of software. You should only download programs from sites you trust.

Unwanted software download warning: You tried downloading a deceptive piece of software. This program, disguised as a helpful download, may actually make unexpected changes to your computer.

Virus detected: Antivirus software detected a virus. Your downloaded file may have a virus and, as a result, the file you attempted to download was removed by the Windows Attachment Manager.

In the above example, note the direct ‘you’ phrasing, the relaxed tone, and the use of may and might to suggest the root cause.

This combination of tone, phrasing, and conciseness is encouraging to the reader as it avoids blame.

You feel whoever write this Help page is on your side.

PS: Get your error message template here.

Posted on

C#: how to write Hello World

The “Hello, World” program is traditionally used to introduce a programming language.

Here it is in C#:

using System;
class Hello
{
static void Main() {
Console.WriteLine(“Hello, World”);
}
}

crone-park (27)

What’s the file extension?
C# source files typically have the file extension .cs.

How to compile?
You can compile the program with the Microsoft C# compiler using the command line:
csc hello.cs

What does the Using directive do?

The “Hello, World” program starts with a using directive that references the System namespace.

What does a Namespace do?
Namespaces
Organize C# programs and libraries into a hierarchy.
Contain types and other namespaces.

For example?

The System namespace contains
a number of types, such as the Console class referenced in the program, and
a number of other namespaces, such as IO and Collections.

Benefits?
A using directive that references a namespace give you unqualified use of the types that are members of that namespace.

In the Hello World example, because we have the using directive, we can use Console.WriteLine as shorthand for System.Console.WriteLine.

The Main Member
The Hello class has a single member, the Main method.

The Main method is declared with the static modifier.
Note:
Instance methods can reference a particular enclosing object instance using the keyword this.

Static methods operate without reference to a particular object.

Where’s the entry point to C# program?
The static Main method serves as the entry point to the program.

What creates the output?

The output is produced by
the WriteLine method of
the Console class in
the System namespace.

Note: C# does not have a separate runtime library. Instead, the .NET Framework is the runtime library of C#.

Posted on

How to Write Release Notes: Faster, Stronger, Better

release notes template in ms word

So, you want to write release notes but don’t know where to start? Well pull you a chair and let me give you the lowdown.

Download – Release Notes template with sample text.

Introduce the release notes with text such as the following:

These release notes provide information about the documentation for <your product> <version number>.

You can download release notes templates here.

About This Release

Next, describe what’s included in the release, especially if it’s quite detailed, for example:

This release is a full version of the <your product> <version number>. It can coexist on the same computer with earlier point releases of the product starting from Version X.x.x.

Identify where you can find the software to download.

Where to find the software to download

To download the software for <your product> <version number>, go to <URL>.

For details about supported hardware and software, see the system requirements.

After you install the software for this release, go to <URL>to download and install any Interim Fix releases. For details about interim fixes, go to the Support website.

For an overview of new features in this release, see the What’s New section.

For answers to Frequently Asked Questions and workarounds for known problems, view the release notes on the Support website.

Prerequisites

Identify any software, drivers, or patches that need to be installed prior to using the application.

What’s New

Next, describe the new features available in this release. These are not enhancements but larger pieces of functionality, for example, a new module, service, window, or other piece of functionality. Enhancements tend to be more related to improvements to existing functionality. For a large release, you might want to keep these separate.

For example:

The following new features are available in this release:

Access management

This release contains an optional feature for managing access to the software. Access management helps you to maintain compliance with the terms of your software agreement. For more information, see the Access Management Guide.

ArcGIS 10.1 support

Geographic Information System Interfaces now support ArcGIS 10.1.

Note: <your product> X.x does not support Microsoft SQL Server 2012 databases.

Compatible companion products

If appropriate, include this section:

You may have purchased one or more <your product> companion products. The following versions of companion products also work with <your product> <version number>: <product x> and <product y>.

Configuration options for <your product>

You can run <your product> <version number> on a system configured in a number of ways. Regardless of how the system is configured, it will contain these elements:

<product>

<product>

<product>

System requirements

Next, identify the mandatory or minimum system requirements:

For information about hardware and software compatibility, see the system requirements document at <URL>

Documentation and Examples

Next, identify any new documentation and code examples

The <your product> documentation is updated for this release and is automatically installed with the product.

Download – Release Notes template with sample text.

Known Issues

Next, identify the features that are now available. Number the features so you can track them.

The following issues have now been resolved.

# Issue Solution

1

2

3

4

5

Enhancements

Next, identify the enhancements that are now available. Number the enhancements so you can track them.

The following enhancements are now available:

# Enhancement

1

2

3

4

5

Deprecated features

Next, identify deprecated features, for example:

IBM defines deprecated as ‘Pertaining to an entity, such as a programming element or feature, that is supported but no longer recommended and that might become obsolete.’ See the IBM Terminology URL: http://w3-01.ibm.com/standards/terminology/cgi-bin/lookup.pl?user_group=corporate

The following features are being marked as deprecated in this release.

Invoke function

Any policy that uses Invoke function can use the InvokeDL function instead. The WSDL file must be recompiled and the policy must be rewritten to accommodate the changes.

Removed features

Next, identify removed features, for example:

The following features were removed from this release:

The graphic view feature in the policy editor.

Integrating with SQL Server.

The following features were marked as deprecated in X.x.x and have been removed from this release.

The following documentation changes apply to this release:

The Troubleshooting Guide has been replaced with a Troubleshooting wiki page available from the following <URL>

Download – Release Notes template with sample text.

Posted on

Proof-reading Checklist for Technical Documents

Is there anything worse than sending out an important document and then, just when it’s gone, finding a typo?

Always leave some time to check your documents before you send them out. Here’s a checklist to get you started.

crone-park (65)

Proof-reading Checklist

  1. Select the entire document – CTRL+A – then click the Language option at the bottomrof the screen. It might say English (United States).
  2. Mark the selected text as the language it should be set to. Click Set as Default.
  3. Press F7 to start the spellchecker.
  4. In the spelling results, click ignore all to ignore the same issue throughout the document. Click Add if you want to intentionally add this word to the dictionary. Be careful if your dictionary is networked as this will be added to their shared dictionary.
  5. Watch for phrasing consistency, e.g. Note and NOTE, iOS and IOS.
  6. Careful making global changes, for example, don’t change IOS to iOS across the document as, fro example, in the code samples, we use IOS all uppercase, not mixed case.
  7. You select and clear check boxes, not untick or deselect. Note it’s check box, not checkbox.
  8. Rephrase text such as you are checking to check, or when you are installing the printer, write install the printer.
  9. When writing file formats, use lowercase. So, it’s an .ipa file not IPA file. An .ipa file is an App Store Package.
  10. Remove abbreviations. Change P4 to Perforce.
  11. Remove rogue double spaces.
  12. Number tasks if they must be performed in a specific order. So, instead of writing, Build the solution in the following order and use bullet points, number each step in relation to the sequence it should be performed. Likewise, avoid using a, b, and c. One tip: select the letter so it turns grey. Then type the number. This instantly changes the letter to a number.
  13. Remove & characters that have crept into the document, for example, find&replace. Instead write Find and Replace. The exception are terms where is should be used, such as R&D, or where it is at least acceptable.
  14. File, Info tab, then update the Properties. Click Show All Properties to see all fields which need to be updated. Remove any legacy text if you’ve copied your working document on another document.
  15. Full stops. If you finish bullet points with a full stop aka period, then check that are all applied.
  16. Ignore text during spell checks.
  17. When everything is finished, Right-click on the Table of Contents, then select Update Entire table. This updates the entries in the TOC and also the page numbers.

If you want to intentionally exclude a block of text, or a specific style, from the spell check:

  1. Select the text that you want the spelling and grammar checker to ignore.
  2. On the Review tab, in the Language group, click Language, and then click Set Proofing Language.
  3. Select the Do not check spelling or grammar check box.

What else would you add?