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 8 Comments

How To Write Technical Documentation For APIs

One of the threads on LinkedIn is how to write technical documentation for APIs. It’s been many years since I’ve documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.

An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.

What is an API?


APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia

Concept

An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.

An API can be:

  1. Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)
  2. Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
  3. Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
  4. Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.

For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.

“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.

API Guidelines

Here are some sites that offer guidelines and examples of API documentation.

Twitter’s API Documentation

Twitter has done a great job documenting its API and breaks out all the different component.

“The Twitter API consists of three parts: two REST APIs and a Streaming API. The two distinct REST APIs are entirely due to history. Summize, Inc. was originally an independent company that provided search capability for Twitter data. The Streaming API is distinct from the two REST APIs as Streaming supports long-lived connections on a different architecture.” http://apiwiki.twitter.com

Tips for writing API documentation

What advice would you give to someone writing their first API document set? What mistakes do technical writers make when approaching this area?

FYI: Twitter API: Up and Running: Learn How to Build Applications with the Twitter API

Posted on

Does your technical writing have an accent?

Maybe you don’t hear your accent, but others do. When you read their documents, does the accent come through? Continue reading Does your technical writing have an accent?

Posted on 4 Comments

Are technical documents a waste of time?

“Don’t worry” she said. “No one reads this stuff anyway. Just get it done.” Sounds familiar? Continue reading Are technical documents a waste of time?

Posted on

How to Write a Target Audience Questionnaire

Creating a training plan? Before you do this, you need to step a step back and work out what your colleagues need to learn. Continue reading How to Write a Target Audience Questionnaire

Posted on

Can Outsourcing Help Your Technical Writing Career?

Daily rates for Technical Writers
Image by Ivan Walsh via Flickr

Most technical writers see outsourcing as a real threat. But, if you look at it from another angle, it’s one huge business opportunity.

Continue reading Can Outsourcing Help Your Technical Writing Career?

Posted on 11 Comments

Is it possible to get into technical writing without a degree?

I got this email during the week. The question was: is it worth the time and money to take a technical writing course?

“I’ve been reading articles about Technical Writing and I’m thinking about a change in career. I’ve worked as a non-degreed Quality Engineer in the manufacturing industries. Writing quality documentations and SOPs was a large part of my duties. In the last 12 years I’ve been employed as a Business Mail Entry Tech with the United States Postal Services. I’m currently making 53K, and with all my benefits add up to about 75K. Writing has always been a love of mine. I’ve been looking for a field that will provide decent living as some sort of writer. After reading your articles I realized that I should take courses in HTML, Frame Maker, etc. Is it worth the time and money to take college technical writing courses?”

Can I get a job as a Technical Writer without a Degree?

Taking the courses won’t hurt, that’s for sure. However, I think we need to step back a second and look at the bigger picture. If you’re thinking of moving into technical writing —and don’t have a technical writing related degree —then, how do you go about it.

My story

I left university in the middle of my computer science degree. This was 20 years back when the economy was even worse than it is now. Partly this was to take up a role in London as a programmer (v low salary but a step in the door) and also to see what opportunities I could generate in a large city versus the small town I was living in.

I moved out of programming and into dtp/technical writing; more out of necessity as the recession got worse and also no-one else wanted to do it!

Several years later, I was working in Sacramento for at Intel on a nice little contract.  That was a start as a freelancer technical writer. I’d held full-time positions now and then but prefer to work for myself.

In that time, I’ve worked in Dublin, London, USA, and Asia. Clients include IBM, Bank of Ireland, Valista, and S1.

So, how much training have I had?

Some courses in UML, Process Design and Oracle, but no formal training courses in Adobe FrameMaker and other technical writing tools.

I didn’t go on the courses because of a) cost, b) time, c) and justification.

Instead I downloaded the applications and trained myself to use them. So, while I’m not a ‘recognized’ expert on Adobe FrameMaker, I know how to get under the hood and get things done.

This meant that when interviewed, I could hold my own and ask the interviewers questions that demonstrated that I knew the applications, making suggestions on how they could resolve their issues and improve working practices and so on.

Having the actual diploma wouldn’t have hurt and if you can get it, then go ahead.

But, by itself, then diploma or degree won’t get you hired.

There are a few reasons for this. What I’ve done next is complied some articles that discuss how to get hired as a technical writer,  especially those who don’t have a degree or are coming into this field from another area, for example, journalism or engineering.

What type of skills do Technical Writers need?

You need enough expertise to understand your audience’s background and their needs. For example, writers who develop documentation for software APIs and other technical subjects are often paid more than those who write guides for a nontechnical audience as it’s difficult to find writers with specialized technical knowledge.

http://www.ivanwalsh.com/2009/06/what-type-of-skills-do-technical-writers-need/

Qualifications for Technical Writers

This article is from a technical writer who started when there were no technical writing qualifications.

“The only requirement was that you had a degree of some sort, and even that wasn’t really compulsory. I know some technical writers who came up through clerical roles. Others, like me, are former programmers. A lot of them are trainers who decided that they could write better training manuals than the ones that were forced on them.”

A journalist who set-up a home office with the aim of becoming a freelance writer, lives in an area that is very IT-connected with many tech writers roles available.

He asks: how important is it for a writer to have a background in IT to be a techical writer in the IT field?

“I have done tech writing in the past (instruction manuals for the pulp and paper industry.) I knew little about the machines for which I was writing instructions, but was able to understand and clearly explain how the machines worked.”

Chris Street says to turn your skills to your advantage. For example:

  • You are a technical writer (you have written instruction manuals)
  • You understand programs from a user’s point of view
  • You can write simply and clearly
  • You are used to writing to deadlines
  • You’re used to writing quickly
  • You’re used to rewriting to editors requirements
  • You’re used to talking to people and getting information which you then turn into documentation
  • You’re used to working with house styles

More: http://www.infinitediversity.com.au/techwriter/archives/71

Chris adds that the two areas non-tech writer friends fall down in (from an IT-related perspective) are:

  1. they don’t know the tools and
  2. they’re not comfortable with project management and the software development lifecycle.

He also adds that most writers are “notoriously bad at selling ourselves, particularly if we have been in one job for a long time. You have to take a long, hard look at what your skills are and produce a marketable resume.”

UK STC on Qualifications for technical writers

The UK chapter of the Society of Technical Communications reckons that it is not necessary to have a degree in technical communication in order to get a job.

Only a small proportion of technical authors in the UK have such a qualification because most of the university courses in technical communication did not start running until the late 1980s or early 1990s.

However, most employers expect candidates to have a degree or equivalent qualification, though they sometimes settle for less in people with good practical experience.

The qualifications demanded depend to some extent on who’s doing the hiring; a Technical Publications Manager is more likely than a Software Development Manager to look for a degree or diploma in technical communication.

Any experience of formal writing is useful, as is a solid grounding in a technical discipline, such as computing or engineering.

http://www.stcuk.org/employment/techwritUK.htm

Education and Qualifications

The Technical Writing Zone makes the point that unlike other professionals, “technical writers do not have to meet specific educational requirements in order to be considered for employment opportunities. Indeed, there are successful technical writers who only have a high school diploma.”

Most technical writers today have a strong educational background. So, although there are no mandatory courses you must take before you can try to pursue a career as a technical writer, it is recommended that you obtain one or more of the following qualifications to increase your chances of success.

http://www.technicalwritingzone.com/technical_writing_required_education_and_qualifications.htm

Technical Writing Specialist Certification

If you want to become a qualified technical writer then the Certified Technical Writing Specialist course is worth a look.

The Certified Technical Writing Specialist (CTWS) is a globally administered credential representing the highest level of certification for professionals who create technical documentation.

CTS sets the credentialing standards for the CTWS credential and develops, maintains and administers the Certified Technical Writing Specialist Examination. CTS provides an objective reference for technical writers to demonstrate that they hold the highest level of core knowledge, skills, abilities and attributes.

The CTWS Candidate Handbook contains sample questions for the CTWS credentialing exam.

UCR Technical Writing Certificate

This Technical Writing Certificate was introduced in 1998 in response to the growing demand to more effectively communicate technical material through manuals, reports and online documentation. The program design provides an integrated curriculum covering principles and practices commonly used in technical environments. The program is designed for those who are looking to accent their current careers or enter an entirely new career focusing on technical writing.

Skills focus on organization, project management, creating user guides and manuals, documenting policies and procedures and writing documentation for online formats.

http://www.extension.ucr.edu/certificates/technical/index.html

Online Brooklyn College Technical Writing Certificate Program

Started in 1999 this program gives students plenty of opportunity to interact with instructors. As of February 2007, people from all over the world have registered for and completed over 400 individual sections of the courses that are offered.

Eight-course program is online: you can take the courses individually, or you can take some combination of the eight courses and earn the certificate—right in your own home and from anywhere in the world. http://www.io.com/~hcexres/brooklyn/index.html

UML Certificate Program in Technical Writing

Those with strong writing skills and an aptitude for computers are encouraged to enter this program. Taught by practicing professionals from the high tech industry, students learn to use the most current technologies and processes.

Students enrolled in this certificate program are eligible for special internship opportunities and can apply for scholarships sponsored by the Society for Technical Communication. http://continuinged.uml.edu/certificates/technicalwriting.cfm

Online Technical Communications Courses

You can selectively take Business & Technical Communications courses without going for a degree or certificate. Students intending to complete the degree or certificate often get jobs during the program and never complete the degree or certificate.

You can register in two ways:

  1. Regular academic credit:  To get a formal academic certificate or degree, you must take courses for regular academic credit. This entails admission to the college and tuition payment according to where you live. You can transfer in any relevant college course work you have done. You can complete the certificate or degree by distance. As a distance student, you can apply local course work to the certificate or degree as long as at least 25% of your course work is “in residence” at Austin Community College. (Online Austin Community College courses are considered “in residence.”)
  2. Continuing education: With this option, you do not have to apply for admission to the college, and you pay the same tuition no matter you live. However, you must “convert” courses taken as continuing education to official academic credit.

If you plan to go for a degree or certificate, contact David McMurrey, department chair, at davidm@austincc.edu or 512.223.4804 for advising. http://www.austincc.edu/tcm/

Recommended Reading:

David McMurrey, mentioned above, has written the best book Power Tools for Technical Communication I’ve seen on technical writing.

It’s not inexpensive, (ok, it’s expensive) but it worth the money if you want a decent primer into technical writing and are considering taking the online technical writing course via Austin University.

Summary

While I believe it’s possible to move into technical writing with a little determination and perseverance, the salary expectations for technical writers is falling. Contracts are also drying up and more IT companies are outsourcing to Eastern Europe, Asia and India.

For this reason, I’d be cautious in moving from a ‘stable’ position, especially if you’re earning 53K, with benefits 75K.

One approach might be to learn some of the tools (e.g. Frame or RoboHelp) and/or writing techniques and try to get freelance technical writing work. If this takes off, then you can give it more consideration and maybe move into it on a part-time basis.

One final thought it that most technical writing roles tend to be in large metro regions. It’s hard to find freelance work in the suburbs unless you live near an R&D centre.

What do you think? Is it possible to get a job in technical writing without a degree? Should this person stay where they are or upskill and move into IT?

Reblog this post [with Zemanta]
Posted on 4 Comments

7 Ways to Improve Your Technical Writing

Here are seven quick tips to improve the quality of your technical documents. Continue reading 7 Ways to Improve Your Technical Writing

Posted on

Why use Master Templates in Adobe FrameMaker?

Master templates let you control the format and positioning of every component in your FrameMaker documents. They are very powerful when they work correctly, but be careful. If you make a mistake, it will take many an hour to clean the documents. Continue reading Why use Master Templates in Adobe FrameMaker?