I'm doing a web site where one of the requirements is Section 508 compliance and I wanted to find an online validator similar to W3C's XHTML and markup validator.

So, I found two online accessibility validators that seem to work well:

http://www.contentquality.com/Default.asp

and

http://bobby.watchfire.com/

Also, Stephen Walther has a good article on MSDN about how to configure your ASP.NET pages and controls for accessibility (credit Brian Russell with the link).

 

In the .NET 1.1 days, documentation could be generated easily and freely using nDoc. Understandably, the fact that it was free is partly why nDoc has now been discontinued.

Since nDoc doesn't support .NET 2.0, you'll need something else to make CHM and other help files for your new Visual Studio projects. That's where SandCastle, the documentation tool recently provided by Microsoft, comes into play. SandCastle is the new free .NET 2.0 documentation tool of choice (if not the only one), and there's a new Septmber 2006 CTP version out. SandCastle is heavily command-line driven, with many steps involved, which is not what I like to deal with when I need to make documentation. I'd rather automate it, which is where SandCastleBuilder (one of several tools that can automate SandCastle steps). Here's a quick walkthrough on how to use SandCastleBuilder and SandCastle to generate rich help files quickly and easily.

Download the Files

• First look in your Add/Remove Programs and remove older versions of SandCastle and any helper UIs. You can keep HTML Help Workshop installed, though.
• Get SandCastle: Go to SandCastle's Wiki at sandcastledocs.com. There should be a link to download the latest version of SandCastle (you can get the September 2006 CTP here).
• In order to generate HTML help 1.x .CHM files (my recommendation), download HTML Help Workshop here. 
• To generate HTML Help 2.0 .HxS files, then
  • If you have Visual Studio 2005, you should download the Visual Studio 2005 SDK here.
  • If you have Visual Studio 2003, download the Visual Studio Help Integration Kit (VSHIK) 2003 here.
• Get a tool to automate SandCastle. I highly recommend Eric Woodruff's SandCastleBuilder -- it looks very similar to nDoc, supports a lot of features, and unlike many of the other supporting tools, it worked for me the first time around and has been updated to support the latest SandCastle CTP. It's interface is a little more imposing than some of the other tools, but you can run it with my of the default settings.

Fixing a bug with the September CTP (optional)

SandCastleBuilder can generate your help files as CHM files, HxS files, and/or as navigatable websites that look a little like MSDN's online documentation. If you only want to make a CHM or HxS file, you can skip this step. Otherwise, if you want to create a navigatable help website you'll need to fix a small SandCastle bug according to the SandCastleBuilder's documentation:

With the September 2006 CTP, when generating the help as a website, the resulting output will cause JavaScript errors when loaded in Internet Explorer. This is the result of a bug in one of the script files that tries to access a style sheet with an MS-Help format URL. Open up the Presentation\Prototypes\Scripts\StyleUtilities.js file in the SandCastle installation folder and change the getStyleDictionary() function to the following:

    function getStyleDictionary() {
        var dictionary = new Array();

        // iterate through stylesheets
        var sheets = document.styleSheets;
        for(var i=0; i<sheets.length;i++) {
            var sheet = sheets[i];

            // It can't handle ms-help URLs
            if(sheet.href.substr(0, 8) == "ms-help:")
                continue;


            // get sheet rules
            var rules = sheet.cssRules;
            if (rules == null) rules = sheet.rules;

            // iterate through rules
            for(j=0; j<rules.length; j++) {
                var rule = rules[j];

                // add rule to dictionary
                dictionary[rule.selectorText] = rule.style;

            }
        }

        return(dictionary);

    }

Configuring a SandCastleBuilder Project

• Open up SandCastleBuilder. If you've used nDoc before you'll notice a similar interface, and you can import old nDoc projects. For this post, though, we're going to start from scratch.
• Pick Project->New Project from Visual Studio Project
• Navigate to and select a Visual Studio Solution file. SandCastleBuilder will ask you which configuration to use for loading assembly information. You can choose your Debug or Release configuration.
• You'll see the assemblies listed under "Assemblies to Document."
• Go ahead and save the Help Project for now by clicking Project->Save Project in the menu.
• In the Build/HelpFileFormat, the default setting is HtmlHelp 1.x. You can change it to other formats if you want.
• In the Build/Dependencies section, you'll need to specify any assemblies your project is referencing. That includes third party DLLs and the .NET DLLs. So, open the Documentation Assembly References dialog and add a folder dependency to the version of .NET you're using (e.g. C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727). Make sure your project is built, and add another folder dependency to your project's bin directory, since third party DLLs will probably be copied there.
• Next, click the Namespaces button in the upper right. Here you can indicate which namespaces should be documented. Normally you wouldn't want documentation for any namespaces that contain web pages. You may have to doubleclick in order to uncheck a namespace. While you're in there, give your namespaces a summary description in the large textfield below the namespace list.
• If you want, fill in the fields in the Help File section like Copyright, Header Text, HelpTitle, etc.

Generate the Help Files

• In the Build/HelpFileFormat, the default setting is HtmlHelp 1.x. You can change it to other formats if you want, e.g. HtmlHelp1.xAndWebSite will give you a CHM file and a web site
• The Paths/OutputPath section determines where your help files will be placed. By default it's in a subdirectory called "Help" inside your project folder. Note that when SandCastleBuilder generates help files, everything in this directory is erased, so if you already have a "Help" subdirectory with stuff in it, change Paths/OutputPath to a different (empty or nonexistent) directory name.
• Go ahead and save your Help Project, then click Documentation->Build Project. It'll take several minutes for your help file to build, so go get a sandwich.
• If the generation ends abruptly with an error saying "Unresolved assemby reference", add that assembly to the Build/Dependencies collection, save the Help Project, and try again.
• You should now have help files inside the Paths/OutputPath (normally <your project directory>\Help). If you set the Build/HelpFileFormat to create a help website, the files will be inside this directory, too.

Automatically Generating Help Files in Visual Studio Whenever You Compile Your Project

If you want to generate your help files automatically whenever you compile a new release version of your project, follow these instructions (from the SandCastleBuilder help):

Right click on the project name in the Solution Explorer, select Properties, and select the Build Events sub-item. Click in the Post-build Event Command Line option to enter the command line to run. You can click the Edit Post-build button to open a dialog with a larger editor and a list of available macros.

In a solution with multiple projects that are documented by the same help file builder project, the post-build event should be defined on the last project built by Visual Studio. If the projects are documented individually, you can place a post-build event on each one.

Below is an example of a common command line script that can be used (lines wrapped for display purposes). Replace the path to the tool with the path where you installed it on your PC, and specify the correct location of the SandCastleBuilder project file (.shfb). The IF statement prevents building the help file in debug builds where it may not be needed.

IF "$(ConfigurationName)"=="Debug" Goto Exit

"C:\Program Files\EWSoftware\Sandcastle Help File Builder\
SandcastleBuilderConsole.exe" $(SolutionDir)Doc\TestProject.shfb

:Exit

Conclusion

That's pretty much it. I'm sure later versions of SandCastle will feature more, but with the right helper tools it's pretty easy to get started.

 

 

 

Atlas, Microsoft's AJAX framework for ASP.NET, has been renamed to ASP.NET AJAX. Not that there's a huge surprise, since Atlas was just a code name. There's no new CTP, although there's a new version (rel 9/14/06) of the Atlas Control Tool Kit with a few new controls.

Scott Mitchell put up a post about a CheckBoxList validator he built for ASP.NET 2.0. Worth checking out. I wrote a custom validator for CheckBoxLists a few weeks ago & while it wasn't too bad, I wish I had waited & just used Scott's. :) Also, he has some good tips about browser compatibility & RegisterExpandoAttribute.

FYI an expando attribute is an arbitrary attribute added to a HTML/DOM object at runtime. Weird name, I know.

...will run slower, because SQL Server will first check the master database for them. Weird but true, according to SQLMag. So, don't start your procs with sp_.

So that my blog shows up on Technorati. Funny, it seems like I did this before. Hmm. Technorati Profile

It's been a while since I posted anything in the management category, so it's time to get caught up. In a past life I was a Software Development Director, so I wanted to write about some things I figured out so that other programmers-turned-sudden-managers have some tips. The below is about goals, and is written for the employee (i.e. the person writing and achieving the goals), but it's equally useful for managers -- just adapt the perspective so that everytime you see the word "You" mentally replace it with "My Employee".

Goals as Performance Review Items

I was thinking the other day about employee goals. Some companies have managers sit down with their employees each year and come up with goals to achieve for the upcoming year. An employee's performance review is then often tied to whether they complete their goals or not. So there's an incentive to be shouting "Gooooaaaaaallllll" at the end of the year.

However, it's hard for many people to come up with their own goals in the workplace. We all know it has to be work-related, and in some professions it's easier than others (e.g. sell 10% more widgets than last year). In fact when I researched this in the past, a lot of the example "good goals" were in terms of manufacturing or sales.

But as a programmer (or other IT worker), in a workplace where priorities can change and projects come and go and get completed in months or weeks, what do you do? What are some goals you can choose and have a chance at pulling them off?

Be Smart About Your Goals

First of all, let's review some basics on goal picking. There's an acronym for good goals: S.M.A.R.T. (or as a friend liked to say, "TARMS"). I've seen many versions of what the different letters mean, but in genenral SMART goals are

• Specific
  • What specifically will you do? Answer the Who, What, Where, When, Why behind it.
  • Bad: "Do a better job of estimating effort" 
  • Good: "Have my actual effort come within 30% of my effort estimates, on average, for my web development projects in the next six months."
  • Other meanings for "S":
    • Stretching: it should be a challenge for you
    • Significant: it should be important
    • Systematic: it should be something you can work on or chip away at
    • Synergistic: working towards the goal should not be at cross-purposes to getting your job done -- you don't want feel like you're stealing time away from your "real" projects to work on your goals. It would be ideal if working towards your goal is incorporated into or part of doing your job. This is particularly important for employees who are already overloaded at work and don't have a lot of free time outside of work.
• Measurable
  • How will you and your manager know if the goal has been achieved? There should be some criteria for knowing that it's been completed. Anyone who deals with project management should be familiar with this theme.
  • Bad: "Learn C#"
  • Good: "Complete a C# class this fall and get a Brainbench C# certification by the end of the year."
  • Other meanings for "M":
    • Meaningful
    • Motivating
    • Memorable
• Acceptable
  • The goal should ideally be set by you, or at least acceptable to you. You should have a desire and willingness to complete it. It should be something you're interested in and that will have real value for you when it's completed (other than just a performance bonus based on goal achievement). For example, will you learn a new skill or technology? Will you feel a sense of pride and accomplishment?
  • Bad: "Devote an extra day a week to code maintenance on our legacy systems" (unless you like legacy maintenance, in which case I have some jobs for you....)
  • Good: "Research new technology and development techniques and deliver a proposal on upgrading some of our legacy systems."
  • Other meanings for "A":
    • Attainable: this is a common meaning for "A". It closely overlaps with Realistic, below. 
    • Action plan: you should put together a plan on how you will accomplish your goal
    • Agreed-upon: similar to Acceptable, it should be something that the manager and employee both agree is a good goal.
    • Accountability: you should be accountable to completing your goal, and failing at it should require an explanation from you as to why. Not achieving your goal should be seen in a similar light as not completing any other project.
• Realistic
  • You should be able to actually attain this goal. It should be a bit of a challenge to accomplish, but not so much that it's a hardship. It should require a level of commitment from you.
  • Bad: "Run 1 mile a month" (too easy) or "Work out twice a day" (too much)
  • Good: "Register, train for, and participate in the marathon this year, including finding a training regimen and/or running club appropriate for beginners"
  • Other meanings for "R":
    • Relevant: it should be relevant to work or your career. It probably shouldn't be "Take a wine-tasting class this fall." FYI, I feel a fitness- or health-oriented goal is OK as long as you have other goals that are more IT-focused. IMO a healthy, fit employee is beneficial to the company because they're less sick, have more energy and less stress, can save the company money on health insurance and/or workers compensation, and can inspire fitness in others. Plus they're better able to help lug those 21" CRTs to the new office. ;)
• Time frame
  • There should be a timeframe or deadline for completion of the goal. This is part of being Specific, but having an end point helps encourage employees to get it done.
  • Time frame also means you should know when you're going to be able to work on your goal. Do you have available time to complete it? When will you work on it? How much time will it require to complete? There are a lot of people who are overloaded at work, working 50+ hours a week, and have full and equally-demanding family lives outside of work. Those people will need to sacrifice something to gain the time they need, or choose goals that don't require as much time, or get their boss to free up their work schedule a bit so they can work on their goals.
  • Bad: "Take a C# class sometime" or "Write a 1000-page book on project management next month"
  • Good: "Take a C# class in the evening next quarter" or "Write an article on project management next month and submit it to at least 3 web sites and magazines."
  • Other meanings for "T":
    • Tangible: a goal that can be measured on paper or in an otherwise physical manner is tangible. But IMO that's too closely tied to Measurable

That's all for today, but next time I'll follow up with more suggestions, guidelines, and ideas for goal-setting in an IT world. I'll write more for the manager's perspective.

 

 

I saw an article today by Stephen Walther about custom validators with ASP.NET. Or I guess it's not so much an article as an excerpt from a book. Anyhow, the article discusses making your own validator controls, and he shows some code (in VB, though, not C#) about how to make a reusable AJAX validator control. It's similar to the CustomValidator, except that it does its validate via an AJAX call. Thay way, if you need to do some expense or fancy server-side validation (e.g. do a database lookup), your user doesn't have to deal with a postback.

I won't make use of it today, but possibly in the future.

I recently needed to strip out non-alphanumeric characters in SQL Server. I initially thought I might be able to use a managed stored procedure and C# regular expressions to do so, but I thought the performance would be bad (e.g. you'd have to cursor through a table, extract a field value, use RegEx on it, go to the next row, etc.). So I came up with the below function using T-SQL's quasi-regular expressions in PATINDEX:

/*******************************************************************
dbo.fnStripNonAlphaNumeric

Removes all non-alphanumeric characters (including spaces) from
@input, e.g.

select dbo.fnStripNonAlphaNumeric('Help, I "think" I''m falling!')

returns

HelpIthinkImfalling

*******************************************************************/
CREATE FUNCTION dbo.fnStripNonAlphaNumeric
(
    @input varchar(500)
)
RETURNS varchar(500)
AS
BEGIN
    
    DECLARE @i int
    DECLARE @result varchar(500)
    SET @result = @input
    SET @i = patindex('%[^a-zA-Z0-9]%', @result)
    WHILE @i > 0
    BEGIN
        SET @result = STUFF(@result, @i, 1, '')
        SET @i = patindex('%[^a-zA-Z0-9]%', @result)
    END

    RETURN @result

END

Then in use it's something like

SELECT dbo.fnStripNonAlphaNumeric(FieldWithAlphaNumerics) as AlphaCleanValue
FROM MyTable

FWIW, to strip non-alphanumeric in C# you can use the one-liner (assuming you have a initial string called "input")

System.Text.RegularExpressions.Regex.Replace(input, @"[\s\W]*", "")

:)