June 04, 2006
|
ASP.NET information resources, Part I
|
7256 hit(s)
We've been giving some thought to the ASP.NET site -- how it looks and works, and especially what type of content is available via the site. As part of that effort, I did an inventory of just what kind of information about ASP.NET we publish or otherwise make available.
I'm going to list the results here, with two goals in mind. One is simply to share what we've done -- this information might be new and useful to you. A second goal is to solicit some input about all this -- about what's on the ASP.NET site (and in the docs), about what you like and don't like about the site (and the docs), and about how we can add to or change the site (and the docs) to be a better resource for you.
In this post, I'll concentrate on the documentation, and list other information resources in another post. Remember, we're interested in your thoughts on any and all of this.
ASP.NET document types
Documentation is broadly categorized into two areas, which we informally refer to as reference and conceptual.
Reference Docs
Reference documentation is "dictionary-style" documentation. We have the following types:
API Reference API reference topics provide concise information about each control, class, event, property, etc. These topics are in a very defined, boilerplate-like format -- member name, summary, syntax, parameters/property values, remarks, etc. In ASP.NET we create API topics for managed reference classes in System.Web, and we separately create topics for configuration elements and for control declarative syntax. For Whibdey, we owned a total of about 45,000 reference topics. Examples:UI Reference UI reference topics describe elements in the UI -- dialog boxes, etc. Example:Conceptual Docs
Conceptual documentation is documentation that reads like an article or book -- "about" and "how-to" type of documentation. We have the following major types.
Overview/Technology Overview Overview topics provide a big picture look at a feature or technology; they can be thought of as an "intro to" type of documentation. The scope can be big — all of Web sites or master pages — or the topic can focus on a specific area within a technology. Examples:How-To A how-to topic is a short topic that describes a specific task, written as one (rarely two or three) numbered, step-by-step procedures. (In ASP.NET docs, how-to topics explicitly include "How to:" in the topic title.) How-to topics do not include in-depth discussion of the topic; instead, they link to otter topics for details. Examples:Walkthroughs A walkthrough is a documentation term for a tutorial. The overall definition of a walkthrough includes these features:- Consists of multiple procedures.
- Generally starts with a blank screen and ends with a running page/project -- the user must be able to see the result of their efforts.
- Is as self-contained as possible, ie, does not constantly link off for other procedures or explanations. (An exception is walkthroughs for advanced topics; in those cases, we might link to procedures for basic tasks such as creating a Web site.)
There is no set time frame for the walkthroughs (e.g., one hour); some are short, some are longer. The ASP.NET 2.0 doc set contains about 65 walkthroughs ranging from the very simplest (creating a basic page) to more advanced (health monitoring and system diagnostics). Examples:Examples The ASP.NET documentation contains some topics structured as relatively large-scale examples -- not just a code snippet within a topic, but a complete, running example. Usually, these are a collection of topics that describe the general implementation, details about the example, and the example code itself. Examples:Those are the major types; we also have "orientation" or "landing page" topics (Ex: ASP.NET Web Parts Pages) and a few others.
Next: Resources beyond the docs.
|
|
