As your development team moves to Microsoft .NET-based projects, your documentation efforts for both your end users and developers should follow. Your current documentation plan is a start, but the introduction of .NET means your technical writers and documentation development efforts must be adjusted.

Typically, a documentation plan is like a project plan and/or requirements document for the technical documentation that is being developed to accompany a software product. It includes guidelines for the documentation structure, format, scheduling, and delivery methods.

Microsoft .NET Framework, user documentation, and online help
The Microsoft .NET Framework does not specify any particular help file format for user documentation. However, the Microsoft HTML Help format is the industry-accepted standard for online help solutions.

Moving to “DocumentationPlan.NET”
DocumentationPlan.NET is not an actual product. I made up the name to emphasize the fact that your documentation will have to upgrade to .NET just like the Microsoft programming languages that have been upgraded to the .NET environment. Microsoft programming shops belonging to the Microsoft developer programs need to update skill sets for both programmers and technical writers so that both groups can deliver .NET-based applications.

To meet the additional needs of .NET, your documentation plan should grow to encompass elements including:

  • Documentation needs of mobile users, including the presentation of text and graphics
  • Online help formats that are accessible across a variety of platforms, including traditional PC Web browsers, PDAs, wireless Web-enabled phones, and other Web-enabled devices
  • Tools for porting print documentation to online formats

While online help is indeed an investment that is sometimes ignored by companies developing software, the mobility element of Microsoft .NET means that users aren’t going to be adequately served and supported by carrying around print documentation with their PDA or other mobile device from which they access applications. The cross-platform and mobility focus of Microsoft .NET has its biggest impact on documentation plans because cross-platform compatibility and mobility are still new ground to many development and documentation organizations.

Additional specific client and user needs aren’t going to be discovered on a technical writer mailing list or in the latest book from a technical writing luminary. Your end users will dictate these needs. For organizations moving to mobile computing for the first time, this is especially true. PDAs and Web-enabled phones may already be standard tools of the trade for the early adopters; less tech-savvy users may need to access a .NET-based application via a mobile device.

As a result, it’s going to take cross-functional efforts on the part of the following staff members:

  • Product managers and/or business analysts who have worked on the customer requirements for the .NET-based product and have insight into customer needs for user assistance, such as documentation and training
  • Technical writers and analysts who take the user documentation online in a medium required for customer access
  • QA staff who test the online help via the various devices used by customers accessing the application

Embracing new cross-platform help development tools
Just like programmers, technical writers can become comfortable with their tools. But the move to .NET often requires the introduction of new documentation tools and methods. The increased need for online help accessible via multiple platforms is often the biggest impact .NET delivers to an existing documentation plan.

The Web services-based nature means online help is the best platform for user assistance and training. Online help can be made available to .NET application users through one of the following methods:

  • Server-based HTML or Web-based help: Such server-side documentation can either be a home-rolled solution or developed with a tool such as eHelp’s RoboHelp Enterprise, which is based on RoboHelp and lets you develop server-based vs. application-based online help solutions.
  • HTML help served from the application itself: There are a variety of tools already available, some of which may already be in your shop.
  • Web help: Either served from the application or from the server side.

Embracing XML and ASP.NET
If your documentation plan does not encompass XML and ASP.NET, your documentation should grow to accommodate it. While the usage of XML and ASP.NET may be transparent to the end users of the application, your software development lifecycle and architectural documentation must address it.

This can take multiple paths, including:

  • Documenting the XML DTD of the application.
  • Documenting ASP.NET code, including general project information, COM objects, and other elements composing the ASP.NET elements of your development project. There are a number of automated documentation tools, such as Living Doc, that automate this chore.

Embracing mobile users
While PDAs have grown in use and popularity, there may be some technical writers and analysts who are not familiar with the PDA environment. Additionally, the functionality of mobile phones is growing in leaps with Web-enabled phones.

If your documentation efforts also extend into end-user training, then you are going to have to meet the needs of classroom and, often, online training, a key strategy for mobile workers. There are tools, such as RoboDemo from eHelp, that enable you to build on-screen tutorials and presentations that run on Pocket PC-based PDAs and can also be accessible from the Web.

Meeting the .NET user documentation challenge
To adjust a documentation plan to meet additional .NET documentation requirements, your user documentation will require some changes and strategy to accommodate the multiple platforms supported by Microsoft .NET and the user community.