This is a great site describing the need for a Software Requirement Specification.
Tag: documentation
NDoc for VS2005
One of the key rights of an open source licence (and therefore a key property of an open source project) is the right to fork. If you think that a project has stagnated or been terminated then you have the right to pick up the pieces and take it in a direction of your own – provided that you have the time, inclination and ability (or can hire someone to do that for you). This is just not available in the closed source world.
NDoc2 died due to lack of resources (and due to the vapourware that is Sandcastle). However NDoc2005 lives on. This is only a beta version. However beta in the open source world means a lot more than beta in the closed source world – especially for a development tool.
This seems to work just fine as is. It creates MSDN style documentation from C# 2.0 source. I had it working without reading the manual in about five mins. This is in comparison to Sandcastle (the microsoft equivalent) where I have yet to generate a single file. This may get my project sufficient documentation to last until Sandcastle catches up (in a year or so).
Sandcastle – Microsofts answer to NDoc
Sandcastle is now available as a CTP.
This is Microsofts answer to NDoc. They have been so sucessful in announcing this product that they have killed off NDoc.
Now if you got a product that was used to generate documentation you would expect it to be accompanied with at least the minimal amount of documentation. In this case not a sausage.
The normal practice for this is to eat your own dogfood and use it’s own codebase as an example.
Wierd Excel Behaviour
The following is the explanation of a very odd excel behaviour:
http://support.microsoft.com/kb/194124/EN-US/
The problem comes when using sql server stored procedures to read data in from an Excel spreadsheet.
The symptom is that Excel will guess the datatype of the columns. If it guesses wrong you get null instead of the data.
I have a general rule of thumb about Excel: if you let it guess it will almost always guess wrong.
Why could microsoft not have added extra connection parameters that allow the caller to specify the data types?
This would not break existing code and would save a lot of heartache.
I have found a workaround:
Export the sheet to tsv and then reimport.
This looses all of the formatting that is getting in the way.
SQL Server 2000 Documentation Bug
I have found out this is how sql servers internal functions work.
This is one of very few places that I have found books online to be wrong.
Books online can be infurating in that even a search for the exact term required will return 50 articles above the one you actually need!
SQL-92 niladic function Value returned
CURRENT_TIMESTAMP Current date and time.
CURRENT_USER Name of user performing insert.
SESSION_USER Name of user performing insert.
SYSTEM_USER Name of user performing insert.
USER Name of user performing insert.
Books online is wrong here
Documentation, What Documentation? Setup.
I have been having fun lately trying to use msdn and msdn2 in order to obtain useful information about the .NET Framework.
This is rather frustrating as it appears that at least 50% of the documentation has been automatically generated from the code and provides little more detail than the intellisense. I would expect examples in all non-trivial classes plus references to related attributes and interfaces. It would also be useful if links to tutorials were included.
Over the past week I have been posting about getting databinding to work in a programatically controlled manner. Most of the information to do this was found via blogs. It appears that MSDN2 has been based upon the maze in Classic Adventure.
Today I have been looking for a tutorial on how to get the Setup project to work. The UI for this in VS2005 is very counter-intuative and the defaults are not very good.
My first step was to go to msdn2 and search for “setup project tutorial”.
The first link is here. This is completely useless. It tells us nothing that you can guess from the IDE. This article is actually part of a crystal reports installation tutorial.
What should you enter as the project name?
After a bit more hunting around I found the following page.
Here is a list of the properties used in the installer.
It would appear that ProductName is a rather important property to be set. This is the one used by the add/remove programs option. Other important items are the version and the Product code.
I intend to follow up on this article with a detailed tutorial on how to write a setup project.
Visual Studio Template : Beyond the basics
The Microsoft documentation in msdn is both complete and lacking.
There is enough detail available to resolve most problems. However the examples are so poor that it can be hard to find out about why you would use them.
For example:
$year$ = this is expanded into the year. This is very useful for compyright headers.
They are also incomplete.
Templates in VS 2005 allow developers to easily replace or add to the items that are available when you select new item.
Templates are zip files containing:
- .vstemplate
- one or more custom files.
By customising these you can save a lot of cut-and-paste time and effort.
This page of Template parameters is not complete.
$safeitemrootname$ = This appears to be the name that the user enters into the dialog.
If you combine this with multi-item templates as defined here. This allows you to use the supplied name as a root of a class. For example you could have a template that takes a name such as Entity.cs that creates the following files:
- EntityModel.cs
- IEntityModel.cs
- IEntityView.cs
- IEntityController.cs
- EntityController.cs
$fileinputname$ = This also work in the template
$XmlConvert_itemname$ = what does this do? I think this is a wizard populated item.
It appears that the WizardExtension appears to work in item templates too despite the documentation.
I will investigate this and will post about it.
Developer Rants 