Room for improvement

Today at work I spent most of the day reading documentation from Microsoft's MSDN web site. I am displeased with the experience for a few reasons:

• AJAX has been around for a few years now, and I still need a full page refresh every time I click a link? It makes it impossible to keep track of the table of contents on the left side.
• Broken links. Broken links are the bane of any website. It's just plain unprofessional. It would also be nice to know if a link was broken intentionally (as in the case of bad documentation) or unintentionally.
• Bizarre URL naming conventions. The document entitled "Mixed (Native and Managed) Assemblies" is available at msdn2.microsoft.com/en-us/library/x0w2664k(VS.80).aspx. I'd prefer something like: ..,/library/vs2005/vc++/guide/interoperability/mixedassemblies.html (Don't click on this, cuz it don't work).

• Too much information and a poor choice of fonts. As you can see below, the size of the font is too small for comfortable reading. The chapter and contents display is almost always going to be truncated.
• Poor search. None of the problems listed thus far would be an issue if the search functionality was better.
  

Lest you think I'm only an engineer on the complain train, over the next few days I'm going to try and put a few sample screenshots of what I think a heavyweight software documentation site should look like. If I don't get too busy.

Upgrading

In all the software projects I've been in, there has been an occasion where a "platform upgrade" has occurred. Unfortunately, the platform upgrade always brings with it a bunch of unforeseen problems.

Here are some pitfalls:

• If you can't migrate/upgrade except in once gigantic leap- you'll fail.
  
• If you can't rollback the upgrade, you will wish you could.

For these reasons, most people avoid being early-adopters. There is too much risk. But it should be noted that the risk isn't so much about whether the new platform/upgrade is beneficial. The risk is in the process of leaping. It almost always isn't as smooth as expected.

Pivotal to an upgrade of a tool or platform is the certification date. The certification date is the date when the product of the new tool is certified as equivalent or better than the previous version. Another important date is the point of no return. That is the date when it becomes impossible or prohibitively difficult to return to the previous version of the tool. Ideally, the certification date should be a long time before the point of no return. If the certification date coincides with the point of no return, you are asking for trouble.

A unique set of problems exist when the version control system undergoes an upgrade. With such an upgrade it is often tempting to use the certification date as the point of no return. This is a common approach because the process of rolling back is very difficult once the migration occurs.

The necessity of rolling back would only occur if the value of the version control system is subordinate to the software's release date. It is not likely that the new version control system has a bug that prevents the release from occurring. It is more likely that the new version control system is misused by developers and thus adds unscheduled delays to development. Also, having the rollback option appeases the risk-averse managerial types.

Here are some suggestions:

• Use a version control system's post-commit scripting capability to push the committed changes to the old version control system. This will permit a rollback after the migration.
• Use the new version control system to perform a software release concurrently with the previous version control system. After a successful release, migrate to the new system. You'll have until the next release to iron out any issues.
• Develop or use an existing tool (like polarion's svn importer).
• Train developers in the new system prior to migration (duh).