locked
Documentation Compiler - Sandcastle

    General discussion

  • We did code complete of documentation compiler ( code named "Sandcastle") on June 15th and currently we are testing the tool building our .NetFramework documentation. We would like to release the CTP version of Sandcastle in Microsoft download center by next week. The perf in our testing has been great as we are able to build the entire framework content in less than 1 hour. I am in the process of going through final check and code signing required to post this in our download center.

    Please expect the CTP in the next week or so and I will provide an update here as soon I post the CTP. 

    Anand..

    Thursday, June 29, 2006 10:58 PM
    Moderator

All replies

  • Good news!
    Friday, June 30, 2006 9:48 PM
  • can't wait!!!
    Saturday, July 01, 2006 6:44 AM
  • It all looks very promissing. I can't wait to get my hands on the CTP to give it a go!
    Monday, July 03, 2006 6:16 PM
  • Hello Anand

    This is really great news! Can't wait!

    Best regards,


    Jeroen Landheer.

    Monday, July 10, 2006 6:32 PM
  • Hello Anand.,

    Is there any news on Sandcastle? Can we expect the CTP soon? I'm really anxious to try it, and from what i can see in this forum, so are others? I would love to see what Sandcastle can do and provide feedback to you.

    Kind regards

    Thursday, July 13, 2006 7:06 AM
  • Well it is the end of that next week that the Sandcastle CTP should be release, where is it?

    I too would love to see sandcastle in action!

    Friday, July 14, 2006 10:26 AM
  • I'm really needing this tool as well. Any news?
    Friday, July 14, 2006 1:33 PM
  • Me too I'm waiting urgently... !
    Friday, July 14, 2006 7:12 PM
  • I think we all are.

    Don't forget that a Program Managers "desire" to release something is not always met.  I think we would all want something usable, installable on a variety of configurations, and able to handle the occasional malformed XML that might occur.

    Also don't forget that this is summer in the upper northern hemisphere and a time when a lot of people take vacations so getting something through verification/validation/QA to release a CTP may not be nearly as quick as say, November or April.  I would imagine that most people in Redmond would not call it their hometown (presuming it's coming out of Redmond).

     

    Friday, July 14, 2006 7:28 PM
  • Thanks everyone for your posts. I have had several emails asking about CTP. There are couple places (download at our download center and also as a part of VS SDK) we are targeting to release our CTP version. The CTP at the download center should be posted by next week and if there are any delays I will post the information here. Also as soon as the CTP is posted I will provide the information here so that you can download and use Sandcastle. In addition we plan to include Sandcastle in our August CTP release of VS SDK.

    Sandcastle Overview:

    • Produces quality, comprehensive, familiar MSDN-like documentation.
    • Works with or without authored comments.
    • Supports Generics and .NET Framework 2.0
    • Sandcastle has 2 main components (MrefBuilder and Build Assembler)
    • MrefBuilder generates reflection xml file for Build Assembler
    • Build Assembler includes syntax generation, transformation..etc
    • Sandcastle is used internally to build .Net Framework documentation

    Let me know if you have any additional questions. My email is listed in my profile and please feel free to reach me directly with any questions.

     

    Anand

    Sunday, July 16, 2006 2:36 PM
    Moderator
  • Thanks for the update Anand!
    Sunday, July 16, 2006 5:29 PM
    Moderator
  • Great, Thanks.  Will this handle non-standard tags (exmple: nested tags named: objects, object, parameters)?  Will sandbox render the content of these non-standard tags in a reasonable format?  If not, will we be to extend the code to format additional parameters ourselves?  We are setting up our documentation format now, and would like to know how to format this type of information.  Thanks, 

    David

    Monday, July 17, 2006 3:05 PM
  • Sandcastle (not sandbox) will not process non-standard tags. However user can post process these tags or extent the transforms (XSLTs) we provide to process these tags.

     

    Anand..

    Monday, July 17, 2006 11:51 PM
    Moderator
  • Will source code be available?

    I know this is a redundant question, but the way in which you've architected the application troubles me.  For instance, in NDoc, [ObsoleteAttribute] was not being documented on enumeration members.  I requested it should be included, and *very* quickly it was. 

    In a recent project, I've generated an additional piece of metadata that I apply to enumeration fields that I would like to be documented (because they really don't have another place to be): I want a particular type of delegate to be associated with a particular enumeration field.  Will MrefBuilder be extensible to support something like this, can it be replaced, or will there be a solution for it?

    Thank you, Anand.  That this is the same tool used to build the .NET Framework documentation is exciting.

    --Robert

    Tuesday, July 18, 2006 6:22 PM
  • Rob,

    Source code for our CTP drop will not be available. We have not made a decision on exposing source code for our RTW release.

    We plan on doing monthly updates and the feature requests should be included quickly.

    I need additional information about your last point and you are wlecome to email me the scenario. The output from MrefBuilder is extensible with custom XSLTs.

     

    Anand..

    Thursday, July 20, 2006 12:31 AM
    Moderator
  • Hi Anand,

    I'm looking forward to seeing the tool. Here are a few things that I would like in a documentation compiler that in some instances I had been thinking about modifying NDoc to do:

    1. Images. I'd like to be able to include references in the XML comments to images from either a local disk source (C:\image.jpg) or web source (http://localhost/image.jpg). I think you could do this in NDoc but it was a bit cumbersome. The images could be class diagrams, sample output, etc.
    2. Include files. I'd like to be able to include a reference in the XML comments to an external XML / XHTML file that would be compiled inline. This should also be local disk source (C:\file.xml) or web source (http://localhost/file.xml).
    3. Directives for how namespaces should be nested in the contents.
    4. Directives to exclude certain files / namespaces from the documenation.
    5. Scriptable from MSBuild, NAnt, etc. I'm sure you'd be allowing for this already but thought I'd put it in.

    That's all I can think of for now. I hope these suggestions are useful and can be included!

    Andy

    Thursday, July 20, 2006 12:50 AM
  • Anand,

    Thank you for being forthcoming about source code availability.  That it's even a decision you are considering is exciting news!  That was one of my favorite things about NDoc - if it wasn't there, I could add it.

    In a project I'm working on, I'm using a custom attribute on the fields of an enumeration to indicate the Type of a delegate that should be used to respond to events.  I chose to do it this way because in situations in which an event is raised and an exception is thrown, callees hooked to the event list after the callee that raised the exception are not called.  I wanted to handle these errors and process the rest of the callee list.

    The following is an excerpt of my enumeration:

    public enum EventType
    {
            [Use(typeof(InfoEventHandler))]
            Info,
            [Use(typeof(ErrorEventHandler))]
            Error,
            [Use(typeof(EventHandler))]
            Authenticated,
    }
    

    The UseAttribute is read by the type that dispatches events, and when delegates are registered for the event, it ensures that the Type of the delegate being registered (it accepts a System.MulticastDelegate parameter) is the same as the Type of the delegate specified by the UseAttribute.

    Basically what I want to know is, will MrefBuilder be smart enough to include the attribute definitions on the fields of the enumeration?  For my project, plugins implement their own EventType-style enumeration, and then plugins that operate as consumers of those plugins consume the events.  Short of looking at IL disassembly or in Reflector, there is no other way to get access to that metadata.  So it's important to me that this be possible in some way.

    Thanks again for your work on this project.  I look forward to seeing it in action.

    --Robert

    Thursday, July 20, 2006 1:25 AM
  • Hey Anand,

    You mentioned that we can expect a drop in a week or so, it is almost three weeks now, any update for us?

    Pieter

    Thursday, July 20, 2006 1:34 AM
  • Come on! I'm sure Anand and his team are as excited as the rest of us to release the CTP. Let's just wait for a little longer.

    Thursday, July 20, 2006 6:35 AM
  • Anand we're excited to hear about Sandcastle.  Thanks for your group's effort to push this initiative.
    Thursday, July 20, 2006 5:21 PM
  • Rob,

    We currently do not build topics for enum fields. I am going to add this a feature request.

     

    Anand..

    Friday, July 21, 2006 12:23 AM
    Moderator
  • Yes and our team is very excited about this release. I will post the Sandcastle MSI this week if our legal and interanl review process is complete. If not I will get them out next week. Just few more days and thanks for your patience.

     

    Anand..

    Friday, July 21, 2006 12:26 AM
    Moderator
  • Hi Anand -

    I'm not looking for enum fields to have their own topics - that would be insanity!  In fact, I don't believe much besides <summary> is valid on enum fields.

    No, what I'd like is for there to be some way to process custom attributes on documentation.  For example, the assembly contains the information that, on those enum fields, the custom attribute is applied.  For instance, when the ObsoleteAttribute is applied to an enum field, when you create the table, it should indicate that the enum field is obsolete.  For instance:

    This is documentation emitted by NDoc on a 1.1 assembly.  Basically, I'm looking to make sure that custom attributes are not simply ignored by MrefBuilder - that instead, they're given an opportunity to be processed by either a plugin or XSLT on the developer's end.

    Thanks again!

    --Robert

    Friday, July 21, 2006 1:21 AM
  • One question - will this tool be able to generate docs from a Web Site project?
    We are currently debating whether its worth converting a large project from Web Site to Web App Project as it caused a few problems when we tried previously. The only reason we need it is to generate docs.
    Friday, July 21, 2006 11:51 AM
  • Robert,

    Yes. The output from Mrefbuilder will have all this infomation. You will be able to modify the XSLTs to process this information.

    Let me know if you have additional questions.

    Anand..

    Friday, July 21, 2006 8:40 PM
    Moderator
  • Adam,

    I am not clear about your question. Could you please elaborate? Are you looking Sandcastle to generate documentation for a website project to document what? Thanks.

    Anand..

    Friday, July 21, 2006 8:41 PM
    Moderator
  • I hope Sandcastle will generate html documentation as well. We had previously relied on NDoc to document all of our web services and class libraries this way, posting them to a common server for the entire company to access via a simple index.html file. MDSN help files don't load over a UNC share :-(.
    Friday, July 21, 2006 8:43 PM
  • To document all the classes in App_Code and all the code-behind and the relatioships between the aspx files, user controls, the code behind files, and the classes in App_Code.

    We've got a massive project, and converting it to a Web Application Project has caused a lot of issues so, as the priority is now getting feedback from beta testers, we need to keep it running smoothly and just ironing out bugs and dealing with feature requests.

    Thanks
    Adam.
    Friday, July 21, 2006 9:12 PM
  •  Bradrover wrote:
    MDSN help files don't load over a UNC share :-(.


    That is incorrect.  There is no problem getting CHM files to load across UNC shares; it just requires a registry change documented in the MS KB.  This was a "fix" in WinXP SP2 and in order to get the behavior back to pre-fix, you merely have to make a quick reg edit.
    Saturday, July 22, 2006 3:07 AM
  • I would also like to know if Sandcastle will have the ability to generate docs for a website project.  We have a large website project that includes numerous classes and types which VS2005 will not currently generate docs for. We are in the difficult position of deciding whether to convert to a Web application project(which seems a step backwards in my opinion), or to convert all of the individual classes and types into their own class libraries(which seem ridiculous as this is not necessary in VS2005 Web Projects and is touted as one of the benefits)

    Si

    Monday, July 24, 2006 4:15 PM
  • Maybe it could be run through Microsoft Connect and get some beta testing done there, where all the feedback support etc is collected...
    Then the legal guys can add their bits to the beta program for it...
    Like all the others in this forum, I too cannot wait for this pending release!

    Regards
    Brian

     

    Tuesday, July 25, 2006 5:13 AM
  • I am also having the same issue in trying to get the .chm file to load on a UNC share.  Can you please provide some further instructions on who,what,when,where,how to reg edit.  Thanks.

    Thanks,

    Please reply to mjoshua@manfinancial.com
    Tuesday, July 25, 2006 7:42 PM
  • Seriously, Google is your friend:

    http://support.microsoft.com/kb/902225/
    Tuesday, July 25, 2006 9:25 PM
  • Adam and Sdix,

    Thanks for providing this scenario. This was not one of our scenarios and test cases for this CTP. However I have added this as feature request. I am going to try our existing build against a web App to see if it works. We will certainly support this for a future release if the current version does not support this scenario. Please fee free ask more questions and I will be happy to respond.

    Anand..

    Wednesday, July 26, 2006 9:11 PM
    Moderator
  • Looks like NDoc 2.0 is dead.  I received this email from Kevin Downs (developer of NDoc) this morning:

    "

    I have decided to discontinue work on NDoc 2.0 and no longer participate in any open-source development work.

     

    The development and release of NDoc 1.3 was a huge amount of work, and by all accounts widely appreciated. Unfortunately, despite the almost ubiquitous use of NDoc, there has been no support for the project from the .Net developer community either financially or by development contributions. Since 1.3 was released, there have been the grand total of eleven donations to the project. In fact, were it not for Oleg Tkachenko’s kind donation of a MS MVP MSDN subscription, I would not even have a copy of VS2005 to work with!

     

    To put this into perspective, if only roughly 1-in-10 of the those who downloaded NDoc had donated the minimum allowable amount of $5 then I could have worked on NDoc 2.0 full-time and it could have been released months ago!  Now, I am not suggesting that this should have occurred, or that anyone owes me anything for the work I have done, rather I am trying to demonstrate that if the community values open-source projects then it should do *something* to support them. MS has for years acknowledged community contributions via the MVP program but there is absolutely no support for community projects.

     

    Once ‘Sandcastle’ is released, it is my belief that it will become the de-facto standard and that NDoc will slowly become a stagnant side-water. This will happen regardless of technical considerations, even if Sandcastle were to be less feature-complete. It's just an inevitable result of MS's 'not-invented-here' mentality, one only has to look at Nant and NUnit to see the effects of MS 'competition'.  

     

    This is not, however,  my only reason for stopping development work - I have a big enough ego to think I could still produce a better product than them :-)

     

    As some of you are aware, there are some in the community who believe that a .Net 2.0 compatible release was theirs by-right and that I should be moving faster – despite the fact that I am but one man working in his spare time...

     

    This came to head in the last week; I have been subjected to an automated mail-bomb attack on both my public mail addresses and the ndoc2 mailing list address. These mails have been extremely offensive and resulted in my ISP temporarily suspending my account because of the traffic volume. This incident has been reported to the local authorities, although I am highly doubtful they will be able to do anything about it.

     

    This has was the ‘last-straw’ and has convinced me that I should withdraw from the community; I’m not prepared to have myself and my family threatened by some lunatic!

     

    Kevin

    "

    Wednesday, July 26, 2006 11:53 PM
  • I'm terribly sorry for Kevin.  This to me is an example why most open source projects can't survive unless they're surrounded by revenue/services (something I don't how could have saved this tool) or sold as nagware.
    Thursday, July 27, 2006 12:04 AM
  • I feel for Kevin, too. I would be just as outraged if members of the .NET community spent their time spamming me instead of helping out on the project.

    However, I disagree that MS are releasing SandCastle to compete with or "stamp out" NDOC. The problem is that there is no competition: there is no NDOC 2.0. The community needs a product to fill the void, regardless of who the product comes from. I don't believe MS would have released SandCastle if NDOC 2.0 was out and going strong.

    Of course, that leads us back to the problem of the community not getting involved in the project. I, for one, have been involved in several community projects (NAntContrib and my own Ingenious MVC). I have been surprised at times by how rude some people can be despite the fact that you work your ar*@ off on a product only to give it away for free.

    RIP NDOC,
    Kent Boogaart

    Thursday, July 27, 2006 12:48 AM
  • I'm not sure what you guys are talking about, but if you read *any* of the mailing lists for the NDOC sourceforge site you would have seen MANY people dying to help Kevin with NDoc2.  He simply wouldn't let them.  I don't feel bad for him per say, because its more or less his own fault.  I'm not saying I don't appreciate all the hard work and effort he put into NDoc, because I do, very much so!  I just don't feel bad for him abandoning the project when he wouldn't let the community help him, and there were plenty willing to help.

    Either way, I'm looking forward to Sandcastle.

    Doug

    I forgot to mention a great post about Kevin's resignation from NDoc. I don't think I could have said it better:

    http://kriscargile.com/blog/archive/2006/07/26/253.aspx

     

    Thursday, July 27, 2006 7:03 AM
  • Wout,
    As I mentioned in my post, I'm sincerely appreciative of the work he's put in to a great piece of software.

    That being said, its open source, you can't expect anything from people in regards to donations.  But the reason I posted was because there were and still are a ton of people that want(ed) to help with NDoc 2.  Why he didn't "let" them help is beyond me.  I can only blame him for that.

    Doug

    Thursday, July 27, 2006 8:46 AM
  • Is there a link to the Sandcastle project site yet?
    Thursday, July 27, 2006 9:09 AM
  • Thanks for your response.

    What would you suggest we do in this situation? Carry on using a Website project and hope Sandcastle supports them soon (i.e. next couple of months) or go through the tedious process (in our case) of converting to a Web Application Project just to get documentation?
    Thursday, July 27, 2006 11:28 AM
  •  Skute wrote:
    Is there a link to the Sandcastle project site yet?


    No, it is an CTP release and as far as i know there is no project site yet.
    Thursday, July 27, 2006 12:47 PM
    Moderator
  • Skute,

    Don't know if this is what you meant, but after the CTP is released, I would love to see a (msdn) blog etc. by the Microsoft team dedicated to Sandcastle.  I am sure I will have a lot of questions, want to see example xslt code, have a place for feedback, want to track development etc.  Anand, if this is not already in the works please consider it.  Thanks.

    Thursday, July 27, 2006 2:33 PM
  • Don't get me wrong folks -- I have a huge amount of respect for Kevin. The guy created an incredibly useful tool, one that has had a huge impact on .NET development. And then he gave it away for free. That's huge. I just don't agree with the way that he's been handing things since 2.0...

    That said, I find blowing away his email or threatening his family appalling. It can't believe that there are those of us out there -- supposed "professionals" -- who would even consider acting in such a way. It's embarrassing.

    Thursday, July 27, 2006 3:19 PM
  • I agree with that. I find it hard to believe a mature professional developer out there could do something like that. It screams of script kiddies, but I doubt they would be so concerned with it's development.

    Oh well, roll on Sandcastle. Looking forward to the release.

    Thursday, July 27, 2006 3:29 PM
  •  drohm wrote:
    I forgot to mention a great post about Kevin's resignation from NDoc. I don't think I could have said it better:

    http://kriscargile.com/blog/archive/2006/07/26/253.aspx

    There is a postscript to Kevin's public letter:

     Kevin Downs wrote:

    P.S. If anyone wants to take over as admin on the SourceForge NDoc project - contact me. If not, I'll be removing myself in 14 days.

     

    I wish I had the bandwidth.  I hope someone does.

    Thursday, July 27, 2006 3:41 PM
  •  Dave Scheffer wrote:

     I wish I had the bandwidth.  I hope someone does.

    Doug Rohm and I have requested that Kevin hand the project over to us. We'll see what happens.

    Thursday, July 27, 2006 3:58 PM
  • That's great news.  Thank you both.
    Thursday, July 27, 2006 4:00 PM

  • It seems like with so much notoriety from having developed NDoc you could have done things like:

    1. Write a book about NDOC and promote it on your website.
    2. Wrote a business plan and asked for venture capital.
    3. Developed some add-on products (filters, special formatters, spin off technologies) which you could charge for.

    The really hard part in software is getting a user base.   You have that.
    Thursday, July 27, 2006 4:12 PM
  • Gentlemen,

    This discussion is taking a ridiculous turn.
    Chatting about how an adult should run his life or business is generally reserved to other kinds of circumstances.

    Thursday, July 27, 2006 4:29 PM
  • Yes we do plan to setup a dev docs and help system blogs with RSS feeds. I am in the process of setting this blog up. This is a great idea and please consider this done.

     

    Anand..

    Thursday, July 27, 2006 4:48 PM
    Moderator
  • Sandcatle generates HTM files and it's fed into the help compiler.
    Thursday, July 27, 2006 5:03 PM
    Moderator
  • I have been following these threads. The mission statement for Sandcastle has been to "Enable managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel".

    Since releasing v1 of the .NET Framework, Microsoft has been encouraging C# developers to document their code using XML documentation comment. We have had several request from MVPs and customeres to release our internal documentation compilers.

    Andrew Webb opened a feature request at http://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=93842

    We are releasing documentation compilers which we have been using for shipping .Net Framework documentation. The goal for this CTP release is to improve performance in the build. we will have new features in our monthly releases.

     

    Anand..

     

    Thursday, July 27, 2006 5:30 PM
    Moderator
  • Am I blind. I saw the original post stated that there should have been a CTP at the beginning of this month. I saw he updated with new features but I didn't see a reason for a time delay or a new estimation for the expected release of ctp. Don't see anything in download center or msdn.
    Thursday, July 27, 2006 9:10 PM
    Moderator
  • Hi MarcD

    I agree with you... I can't find the CTP anywhere... Maybe because it hasn't been released yet? I guess we need to be patient...

    Best regards,


    Jeroen.

    Thursday, July 27, 2006 9:50 PM
  • Check out http://blogs.msdn.com/sandcastle/. Thanks for the suggestion.

    Anand..

    Thursday, July 27, 2006 11:01 PM
    Moderator
  • Marc,

    We have not released the CTP yet. Please check out http://blogs.msdn.com/sandcastle/ and I will do a post as soon as the CTP is out of the door. We are very close and thanks for your patience.

     

    Anand.

    Thursday, July 27, 2006 11:02 PM
    Moderator
  • Adam,

    If you can generate dlls for your code behid CS files then you can generate documentation. We provide a test.cs file in Sandcastle example directory and steps to create documentation for it. I would wait until we release the CTP.

     

    Anand..

    Thursday, July 27, 2006 11:52 PM
    Moderator
  • That's great - thanks for setting up the blog!
    Friday, July 28, 2006 8:58 AM
  • Should I be the first to thank Microsoft for producing Sand Castle?

    The number of unnecessary steps and command line statements one has to execute to do anything is surpassed only by most Open Source projects.

    The fact that Microsoft developers working on this project DID NOT take 5 minutes to produce a batch file that worked simply by going CreateOutputThatReducesTheNumberOfUnnecessaryStepsfrom11To1.bat "YourDllFileGoesHere.dll" is extremely warming.

    I want to thank Microsoft for requiring other developers to step forward and show their leet batch skills. Yes To all the people that posted solutions, every single person in the world installs their stuff to "C:\Program Files" and every single person wants to put your stuff in their root "C:\" directory and every single person has a C:\ and uses it as their main drive. And every single person wants to have to go through the scripts and edit all of these ridiculous paths to point to valid locations.

     

    And when this is all said and done, and 3 scripts have been tried and one script has been rewritten eliminating the aforementioned problems we are given a 24kb chm file that has a single icon. An Alert Icon. No security warning. No contents listing my public classes and their methods, and the enumerations and the comments from the assembly that it took. Just a blank icon.

     

    Thanks a million.

    Tuesday, August 01, 2006 1:42 PM
    Moderator
  • MarcD,

    I was very disappointed to read your post. The people on the SandCastle team have worked hard to release a build of a product with which you have met with negativity and sarcasm.

    The SandCastle version released was the first CTP. What did you expect? An RTM build as a CTP? Your attitude is the very reason why people like Kevin stop working on products like NDoc that they give away for free.

    Why don't you start being part of the solution.

    Tuesday, August 01, 2006 2:10 PM
  • Hey, take it easy on them (and us).. it's just a very early CTP you're looking at.

    I bet you that when the 1.0 release is out it will be fully integrated in Visual Studio. Btw, my MSBuild script should be very easy to modify so that it looks somewhere else than in c:\Program Files etc:

    http://blog.ljusberg.com/2006/07/msbuild-script-for-sandcastle.html

    If you don't get it working, let me know and I might be able to help you out.

    Cheers,

    Anders

     

    Tuesday, August 01, 2006 2:11 PM
  • Just thought I'd let you know how to modify the msbuild script mentioned above to work with different setups.

    1) Instead of extracting the Sandcastle.zip file to c:\Program Files\MSBuild, extract it to the equivalent MSBuild folder (d:\Program\MSBuild or whatever)

    2) Open up the Sandcastle.targets file in any xml editor, and change the SandcastlePath property to point to your Sandcastle installation (maybe d:\Program\Sandcastle) and the HtmlHelpCompilerBin path to point to wherever HTML help workshop is installed (say d:\Program\HTML Help Workshop).

    After that, it should work fine again.

    /Anders

    http://blog.ljusberg.com/2006/08/sandcastle-msbuild-script-for-non.html

    Tuesday, August 01, 2006 6:41 PM
  • MarcD,

    What an ignorant comment.  I'm not sure how these things work, but if I could I would vote for your "MVP" status to be revoked.

    Tuesday, August 01, 2006 8:50 PM
  • So in your opinion, all an MVP should ever do is cheer every new Microsoft release, no matter how lackluster?  Also, please don't use "ignorant" as a general-purpose insult... there was nothing "ignorant" about his comment.

    Microsoft claims this Sandcastle release is an early preview but they also claim that this same application has been used all the time to create their own MSDN documentation.  Also, several weeks have passed since the first Sandcastle announcement -- time that was supposedly spent to properly wrap up this first public release.

    Given that, the current state of Sandcastle is definitely disappointing.  On top of the incredibly convoluted usage, Sandcastle is apparently also unable to link to an installed MSDN Library and does not support popular NDoc tags like <overloads>.

    I think Kevin was hasty in abandoning NDoc for fear of Sandcastle... the application shows promise but it has a long way to go before it's an acceptable replacement.  I'll keep using NDoc 2.0 Alpha, thanks.

    Wednesday, August 02, 2006 6:19 AM
  • Actually I think a lot of people were disappointed by the CTP also. I also believe that the steps should be much less even from the first CTP. As far as I'm concerned, I didn't even tried to use it.

    This is my direct opinion without sarcasm. I will expect the next release and the final product since documentation compiler is really missing from VS.

    Keep up the good work which I'm sure you are doing. It's just that some of us will have to wait a little longer to see.

    Regards,
    Dimitris

    Wednesday, August 02, 2006 7:11 AM
  • Not at all.  MVPs can certainly express disapproval over Microsoft's choices.  My objection is to his tone -- it's basically a "thanks for nothing" attitude that unfairly damnifies the effort put forth by the Sandcastle team.  We have no way of knowing why the team didn't provide a script... perhaps they have been busily working to make the actual function of the product as stable as possible?  Perhaps they are internally using a VS add-in that isn't ready for release... it's all speculation, nobody on the outside knows, and it's a reprehensible form of anti-community behavior to spout such nonsense.  The team has put themselves out there with an early release, and to our benefit.  I certainly don't think that the team has been sitting around doing nothing since the first announcement -- note that most of the posts by the team on the Blog that was set up last week are from over the weekend.  When I read back through this thread I see several instances where the team has welcomed feature requests.  Clearly they're dedicated to the project.

    If responses like MarcD's become a norm of the community (and the community doesn't respond by calling them out for what they are), Microsoft's public relations people will take notice and we'll go back to seeing releases much later in the development cycle -- that doesn't help anybody.

    Kevin didn't abandon NDoc strictly because of Sandcastle -- he says that clearly in his message.  He did it because of events that occurred as a result of the general attitude of entitlement that some people in the community seem to have.  Your comments about what Sandcastle doesn't support indicates that you clearly have it as well.  Nobody said you have to use Sandcastle -- continue using NDoc 2.0 Alpha, by all means... but remember that the reason that it won't be finished is precisely because of the perspecitves held by people like you and MarcD.

    Wednesday, August 02, 2006 2:44 PM
  •  Chris Nahr wrote:
    Microsoft claims this Sandcastle release is an early preview but they also claim that this same application has been used all the time to create their own MSDN documentation.
    No they don't.  They specifically say the CTP is a new architecture.  Clearly this means it *hasn't* been used to generate any publicly available MSDN documentation.

    As they dogfood, I'm sure *many* improvements/fixes will be added.

    I'd much rather have the ability to get involved with the product at this stage then wait for some arbitrary set of criteria be validated before being able to use it.

    The CTP is to garner feedback.  Clearly the designers are looking for the community's opinion on usability, look-and-feel, etc.

    To simply say "thanks for nothing" is not productive, reduces the chances that future projects of this type (or any type) will even be made available (look at Kevin's response to the "gimme" attitude of the community), ruins it for the rest of us, and it just plain rude.  If you don't like the product either shut up and don't use it or be a productive member of the community.  All that was required was a comment like "I was disappointed with the number of steps needed to produce output.  I suggest <enter suggestion here>...".  Look at Anders' response to the whole thing.  Clearly more proactive and productive, and provides feedback that the designers can actually use.

    Look at Kevin's complaint-to-pat-on-the-back-ratio; a million to one! (irrespective of his criteria for pat-on-the-back, or the liklihood that he put himself in that position)  Not really incentive to continue similar work for "the community".

    Wednesday, August 02, 2006 3:21 PM
    Moderator
  • This is getting ridiculous.  Can we please stop pretending that Sandcastle was made by private individuals (like Kevin Downs) out of the goodness of their hearts?  These people are Microsoft employees, they are being paid for what they do, and what they do is fulfil a request by Microsoft's paying customers (such as me) to add a feature that's obviously missing from the current Visual Studio release.

    You know, take the XML comments from a compilation run and turn them into an actual usable help file.  Not such an outlandish and extravagant idea, you will admit.  One might reasonably say this feature should have been available when Visual Studio 2005 or even 2003 was first released, at least in the Professional edition and up.

    As to the current Sandcastle release, I stand corrected regarding Microsoft's own use of the product but I still say that a release at this early stage is simply not helpful.  I'm baffled what sort of constructive feedback is even expected here -- the project lead already wrote up the sequence of steps required to build a CHM file in his blog, yet the extremely obvious action of putting these steps into an executable script is such a huge mental leap that the community has to help out?  Give me a break.

    Microsoft aren't doing their own reputation any good by releasing those increasingly early and incomplete preview versions of their products.  It's disappointing that Microsoft releases take so long to begin with, but an unusable release is worse than no release.  Sandcastle needs at least some basic level of polish before the team can reasonably expect useful feedback.

    Thursday, August 03, 2006 6:43 AM
  • While waiting for a nice polished Microsoft-built GUI, I again decided to take on the task myself. If anyone is brave enough to install my first attempt at a Visual Studio Project plugin, head over to http://blog.ljusberg.com/2006/08/sandcastle-visual-studio-project.html.

    Features:

    • New project type "Documentation Project"
    • Add assemblies/XML-files from the current solution, and/or from external files.
    • Build the same way you would any other project in Visual Studio

    It most likely also features a whole lot of bugs, so be warned..

    /Anders

    Thursday, August 03, 2006 1:35 PM
  • I disagree with Chris Nahr, I thank the dev team on this for getting this release out as quick as they could. Yes it is frustrating that it isn't intuitive to use, but that will come with time.

    I'm sure that a lot of people waiting for this release are like me, in that they'd rather something was released now so they can create documentation for their projects, rather than wait, weeks or months until it is a little more polished. That way if you'd rather wait for the finished product, you can. If you need something now and are happy to spend a little of your time to write a script to get it to work, you also have that option open to you.
    Thursday, August 03, 2006 1:57 PM
  • Anders, your contributions are much appreciated!!!  I've started documenting our large project using your MSBuild tasks and sandcastle.  There are a couple of things I'm trying to change (some small some big) which I wonder whether you or the general audience have opinions on.

    1) I can't seem to get content on that "front" page that just shows the alert icon.  Anybody succeeded on that one?

    2) We have lots of nested namespaces, because the product is big.  I personally think nesting those sub-namespaces (AALabs.Foo.Bar inside AALabs.Foo) is better for us.  It's unclear how this occurs now... I read the XSL and the input XML and the topic list doesn't seem to have any hierarchy in the first place, I'm not sure how the hhc ends up with it.  That said, I can modify the hhc programmatically, and maybe that's the answer.  I'm not sure XSL is up to the task of splitting and sorting it all out anyway.

    3) This is too big to be a bullet item, but I really want to figure out how to integrate class level docs with a Wiki.  We use Confluence here.  I can imagine modifying the style sheets to produce wiki markup instead of HTML Help, but the magic part is how might we then take changes back into the comments.  Or perhaps this isn't the right model at all, perhaps it should be "read only" with discussion in the wiki.  Anybody else dealing with this?
    Thursday, August 03, 2006 2:41 PM
  • I'm afraid I've been so busy automating the current process that I haven't looked that much at the stuff that is actually produced. But I figure you could do a lot of things with the xml and xsl files.

    About the wiki, I'd probably suggest going the same way that the msdn-wiki is going (http://msdnwiki.microsoft.com/), ie. the documentation is read-only but with a discussion below it. Incorporating changes back into the original comments would probably be really difficult..!

    /Anders

    Thursday, August 03, 2006 2:56 PM
  •  Chris Nahr wrote:
    ...but I still say that a release at this early stage is simply not helpful.  I'm baffled what sort of constructive feedback is even expected here -- the project lead already wrote up the sequence of steps required to build a CHM file in his blog, yet the extremely obvious action of putting these steps into an executable script is such a huge mental leap that the community has to help out?  Give me a break.

    Hmm, let's see.  Perhaps feedback on the actual function of the product?  For instance, how about "I tried to document an assembly that uses feature X, and didn't get a correct result."  Or maybe, "I'd really like to be able to use some NDoc features like P, Q, and R... here is how I would like to see them supported."

    Personally I am thrilled to see Microsoft finally starting to embrace some of the best attributes of the open source community, even if they haven't embraced open source itself.  Anders' contributions are a great example.  This whole experience really makes me wonder how many other useful pieces of code Microsoft has internally that they would be willing to release to the community if they could expect others to help out?

    Should Microsoft have released this feature way back with VS 2003?  Absolutely.  They didn't for their own reasons, but they're doing it now.  We should support them and try our best to provide positive feedback.  Not such an outlandish and extravagant idea, you will admit. 

     

    Thursday, August 03, 2006 3:42 PM
  •  Chris Bray wrote:
     Chris Nahr wrote:
    ...but I still say that a release at this early stage is simply not helpful.  I'm baffled what sort of constructive feedback is even expected here -- the project lead already wrote up the sequence of steps required to build a CHM file in his blog, yet the extremely obvious action of putting these steps into an executable script is such a huge mental leap that the community has to help out?  Give me a break.

    Hmm, let's see.  Perhaps feedback on the actual function of the product?  For instance, how about "I tried to document an assembly that uses feature X, and didn't get a correct result."  Or maybe, "I'd really like to be able to use some NDoc features like P, Q, and R... here is how I would like to see them supported."

    Agreed.  As much some members of the community seem to believe it's their inalienable right to have some sort of XMLDoc-to-CHM conversion, comments like "thanks for nothing", "I don't like it", "it doesn't do what I want", "it's not useful", etc. are just going to make the people working on it (yes, they work for Microsoft, but they're still people) think they just shouldn't bother--nothing is good enough, so why waste time, nothing is what the community will get.  "Hmm, bust my *** working on something to get negative comments, or don't bust my *** and get negative comments": seems like an obvious choice to me!

    If you're not willing detail the criteria by which any application does not meet your needs, you cannot expect to ever meet your needs.  If you're not willing to detail the failure criteria, then keep silent. I don't care who's working on it.  If a user of software that you wrote came to you an said "I can't use it, it doesn't work" what would *you* say?

    Thursday, August 03, 2006 4:14 PM
    Moderator
  • Please all.  Stop the drama or take it to UseNet.
    Thursday, August 03, 2006 7:07 PM