Expert One-on-One™ C# Design and Development

Chapter 13. Considering the Documentation

Not every developer out there hates writing documentation, but you'll likely find that a vast majority of developers do hate the job. Writing documentation is a difficult task — writing great documentation that other people will understand is even harder. Unfortunately, without documentation, you can't expect anyone to understand and use your application. Most people can't simply look at the user interface and know what to do immediately. Even developers need help when it comes to working with someone else's documentation. This chapter helps to ease the pain. Fortunately, there are guidelines you can use to write good documentation. You'll find guidelines for the three main user types of your application: developers, administrators, and users.

In addition to user-level documentation, you must document the application code. Poorly documented code is hard to follow, difficult to maintain, and impossible to fix. Some projects become so difficult to fix that the developers who have to work on it throw up their collective hands and ask to start from scratch. This chapter looks at a number of ways to create comments and use them to generate XML documentation that others can use with your application to maintain it with greater ease. Once you have an XML file containing code comments, you can use it in a number of ways, employing the technologies that Microsoft provides. This chapter also reviews these alternative uses for your documentation.

Some ...