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 Files\microsoft shared\MSEnv\VsLangproj.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.0\Common7\IDE\Extensions\Microsoft Corporation\NuGet 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.