Ian, I completely disagree with the proposition that the SDK-docs would serve no purpose for end-users.
The *extensibility* of NAnt is definitely end-user functionality; of all the things that NAnt has going for it, it is one of the bigger ones. It should be possible to create your own tasks, types, and functions using no more than the binaries and their documentation. In fact, this is true for anything you make that you expect others to use: requiring the users of your stuff to reverse-engineer the manual from source is inconsiderate an unprofessional. I am responsible for the introduction of NAnt in a biggish enterprise and the vast amount of red 'Missing <summary> documentation ...' is for me both embarrassing and worrying. It is embarrassing because it challenges the wisdom of my choice; I can only apologize to my co-workers and defend NAnt is an "otherwise highly professional" tool. It is worrying because it strikes me as a "broken window": if something is not done about it asap, it will rapidly get worse. I'd really hate to see NAnt loose out to MSBuild for no other reason than amateurish carelessness with the documentation. cheers, rutger dijkstra > Date: Mon, 15 Nov 2004 22:28:15 +0900 > From: Ian MacLean <[EMAIL PROTECTED]> > To: Gert Driesen <[EMAIL PROTECTED]> > CC: [EMAIL PROTECTED], [EMAIL PROTECTED] > Subject: Re: [Nant-users] Content of distributions ? > > Gert Driesen wrote: > > >Hi, > > > >Right now, the zip & tar flavors of our distributions have the same content. > >I wonder if it makes sense to include the SDK docs in HTML Help format for > >the (gzipped) tar flavor, as these target *nux anyway. > > > > > that probably doesn't make much sense if we assume that Windows users > will use the zipped version. > > >Should we replace the HTML Help format SDK doc with the plain HTML format > >for the tar files ? > > > > > > > makes sense. > > >Does it make sense to include the SDK docs for all NAnt assemblies, or > >should we only provide the SDK docs for the NAnt.Core assembly ? > > > > > > > Does anyone actually use the SDK docs ? I'm not saying that they aren't > useful but personally I tend to go straight to the source. However I > take your point in that NAnt.Core has most of the types that you would > be looking up info for - the other task assemblies contain mostly just > task definitions. So I would say that limiting the SDK doc to NAnt.Core > and perhaps NAnt.Dotnet ( it has some commonly used DataTypes defined ) > makes sense. > > >Does it make sense to include the SDK docs in the binary distributions ? > >Wouldn't developers download the source distributions anway ? > > > > > That also makes sense. The average end user has no use for the SDK doc I > think. > > Ian ------------------------------------------------------- SF email is sponsored by - The IT Product Guide Read honest & candid reviews on hundreds of IT Products from real users. Discover which products truly live up to the hype. Start reading now. http://productguide.itmanagersjournal.com/ _______________________________________________ Nant-users mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/nant-users
