Release Notes – How to Write ‘Known Issues’

This week we look at how to document known issues in release notes.

The Release Notes web page on the NuGet site offers good examples of how to document known issues in release notes.

We’re going to look at three common issues:

  1. Installation issues
  2. Known issues
  3. Workarounds

Let’s see what we can learn from it.

Known Issues with NuGet

First, the first identifies its purpose in clear language.

It then identifies the situation, problem, gives an example, and offers the solution.

The structure is as follows:

  1. Situation
  2. Problem
  3. Example
  4. Solution

Situation

These are the most common known issues with NuGet that are repeatedly reported.

If you are having trouble installing NuGet or managing packages, please take a look through these known issues and their resolutions.

Error installing packages with NuGet 2.7

Problem

In NuGet 2.7 or above, when you attempt to install any package which contains assembly references, you may receive the error message “Input string was not in a correct format.”, like below:

Example

PM> install-package log4net

Installing ‘log4net 2.0.0’.

Successfully installed ‘log4net 2.0.0’.

Adding ‘log4net 2.0.0’ to Tyson.OperatorUpload.

Install failed. Rolling back…

install-package: Input string was not in a correct format.

At line:1 char:1

It then explains why this issue occurred and how to resolve it.

“This is caused by the type library for the VSLangProj.dll COM component being unregistered on your system. This can happen, for example, when you have two versions of Visual Studio installed side-by-side and you then uninstall the older version. Doing so may inadvertently unregister the above COM library.”

Solution:

The next paragraph is the solution to the issue.

Your goal as a tech writer is to provide the specific instructions so the reader can follow the instructions and fix their issue.

Identify any prerequisites in advance.

Run this command from an elevated prompt to re-register the type library for VSLangProj.dll

regsvr32 “C:Program Files (x86)Common Filesmicrosoft sharedMSEnvVsLangproj.olb”

If the command fails, check to see if the file exists in that location.

Known Issues

If you know something is an issue, state it. This ensures customers don’t waste their time trying to get it to work and sending in tech support requests.

Identify the known issue. Explain where it occurs.

Write-Error command doesn’t work inside install.ps1/uninstall.ps1/init.ps1

This is a known issue.

Workarounds

Workarounds are common in particular when software is immature and just released. In time, most Workarounds are resolved.

Here’s an example of how to document a workaround.

Attempting to uninstall results in the error “Cannot create a file when that file already exists.”

For some reason, Visual Studio extensions can get in a weird state where you’ve uninstalled the VSIX extension, but some files were left behind.

To work around this issue:

  1. Exit Visual Studio
  2. Open the following folder (it might be on a different drive on your machine)
  3. C:Program Files (x86)Microsoft Visual Studio 10.0Common7IDEExtensionsMicrosoft CorporationNuGet Package Manager<version>
  4. Delete all the files with the .deleteme extensions.
  5. Re-open Visual Studio
  6. After following these steps, you should be able to continue.

You can read the rest of the Nuget release notes here.

Summary

Those were three examples of how to write the known issues section of Release Notes.

Next week, we look at how to document enhancements.

Download these templates to start

Acceptance Test Plan

Contingency Plan

Software Development Templates

Acquisition Plan

Conversion Plan

Software Requirements Specification

Action Plan

Cost Benefit Analysis

Software Testing

API Documentation

Database Design

Standard Operating Procedures (SOP)

Audience Analysis

Datasheet

Statement of Work

Availability Plan

Deployment Plan

System Administration Guide

Bill of Materials

Design Document

System Boundary

Business Case

Disaster Recovery Plan

System Design Document

Business Continuity

Disposition Plan

System Specifications

Business Plan

Documentation Plan

Technical Writing Templates

Business Process

Employee Handbook

Test Plan

Business Requirements

Error Message Guide

Training Plan

Business Rules

Expression of Interest

Transition Plan

Capacity Plan

Fact Sheet

Troubleshooting Guide

Case Study

Feasibility Study

Use Case

Change Management Plan

Functional Requirements

User Guide

Communication Plan

Grant Proposal

Verification and Validation Plan

Concept of Operations

Implementation Plan

White Papers

Concept Proposal

Installation Plan

Work Instructions

Configuration Management Plan

Interface Control Document

Software Development Templates

Acceptance Test Plan

Maintenance Plan

Software Requirements Specification

Acquisition Plan

Market Research

Software Testing

Action Plan

Marketing Plan

Standard Operating Procedures (SOP)

API Documentation

Needs Statement

Statement of Work

Audience Analysis

Operations Guide

System Administration Guide

Availability Plan

Policy Manual

System Boundary

Bill of Materials

Project Plan

System Design Document

Business Case

Proposal Manager Templates

System Specifications

Business Continuity

Proposal Template

Technical Writing Templates

Business Plan

Quality Assurance Plan

Test Plan

Business Process

Release Notes

Training Plan

Business Requirements

Request for Proposal

Transition Plan

Business Rules

Risk Management Plan

Troubleshooting Guide

Capacity Plan

Scope of Work

Use Case

Case Study

Security Plan

User Guide

Change Management Plan

Service Level Agreement (SLA)

Verification and Validation Plan

Communication Plan

Setup Guide

White Papers

Concept of Operations

Social Media Policy

Work Instructions

Concept Proposal

Contingency Plan

 

Configuration Management Plan

Conversion Plan