About

I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search


(Supports AND)

Google Ads

Feed

Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.

Quote

It has been remarked that Mr. Pecksniff was a moral man. So he was. Perhaps there never was a more moral man than Mr. Pecksniff: especially in his conversation and correspondence. Some people likened him to a direction-post, which is always telling the way to a place, and never goes there.

— Charles Dickens



Navigation





<October 2021>
SMTWTFS
262728293012
3456789
10111213141516
17181920212223
24252627282930
31123456

Categories

  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  
  RSS  

Contact Me

Email me

Blog Statistics

Dates
First entry - 6/27/2003
Most recent entry - 9/13/2021

Totals
Posts - 2638
Comments - 2643
Hits - 2,415,950

Averages
Entries/day - 0.39
Comments/entry - 1.00
Hits/day - 361

Updated every 30 minutes. Last: 2:34 AM Pacific


  01:43 AM

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.

[categories]  

[1] |