Kerry Jenkins

What is the plan for delivering the released version of Sandcastle

Thanks,

Kerry Jenkins



Re: Developer Documentation and Help System Sandcastle Roadmap

Anand Raman - MSFT

Kerry,

Thanks for your question and for using Sandcastle. We have had similar question about Sandcastle in the past. When I released Sandcastle last year (July 2006) as CTP the goal was to release a 1.0 version early this year. Sandcastle is used for shipping Orcas (VS 2008) Beta 1 and Beta 2 documentation including the Framework documenttion.

We did a code complete early this month for the version of Sandcastle that will be used for shipping Orcas RTM documentation. We have made some exciting chnages to VS 2005 document model and I will post a blog about this. We plan to release this version of Sandcastle in the next couple weeks at our download center. We will also be shipping this version in VS SDK.

What is preventing us from calling this "released" or 1.0 version

Nothing releted to the stability of the code base of Sandcastle. I believe Sandcastle is in a state that we can call it 1.0 as use it to ship Framework documentation.

However we have not made any determination on how Sandcastle should be shipped as 1.0 Should we continue to make Sandcastle available as stand-alone downloads Should we integrate Sandcastle into VS Pro editions. Shoud Sandcastle be a part of the Team Foundation msBuild process Hopefully we can make this decision quickly and release 1.0 version.

What do you think How should we ship Sandcastle Please let me know your thoughts Cheers.

Anand..






Re: Developer Documentation and Help System Sandcastle Roadmap

Kerry Jenkins

Anand,

Thanks for your quick response.

I would like to see Sandcastle continue to be available as a stand-alone download. Integration into the VS Pro editions would be great but not worth holding back the stand-alone product. Integration into Team Foundation msBuild process would be nice too but not as important as stand-alone or VS Pro integration.

Kerry





Re: Developer Documentation and Help System Sandcastle Roadmap

EWoodruff

Hi Anand,

If you do create a version integrated with VS Pro or Team Foundation, I'd still like to see a standalone version that we can use outside of Visual Studio. If not, you leave out everyone using the express and standard editions and many others using an alternative such as SharpDevelop. I think integrating it into VS would also limit the extensibility of the build process somewhat. Having the standalone tools still lets us wrap our own build process around them if necessary and extend it ways that you might not have considered yet.

Eric





Re: Developer Documentation and Help System Sandcastle Roadmap

Dave Sexton

Hi guys,

I agree with Eric that if the Sandcastle team is going to release a VS-integrated version it shouldn't be any less powerful, extensibility-wise, as the current CTPs are. But I do believe that if it's architected correctly, a VS-integrated version could be more powerful and certainly easier to use than the current CTP is, which is of course why I wrote DocProject Smile

- Dave






Re: Developer Documentation and Help System Sandcastle Roadmap

Henning Krause

You should keep it stand-alone. If you integrate it into Visual Studio, how many update (read: Improvements/new features) will we see Probably only some CTPs until the next Visual Studio version ships.

If you keep it stand-alone, you can develop it more quickly.

Apart from that, you could certainly publish an addin for Visual Studio to integrate it without giving up your indepdence here...

Henning





Re: Developer Documentation and Help System Sandcastle Roadmap

Dave Sexton

Hi Henning,

And how will that differ from what's been happening for the last year or so They've only been shipping CTPs anyway, and "developing it quickly" doesn't appear to be the case...

Now that Sandcastle has been out in the community for a while, they should have more than enough feedback to make a useful, flexible version that's integrated into VS 2008 with designers and docked tool windows (although it's probably too late for that now - maybe Rosario is more realistic.)

- Dave






Re: Developer Documentation and Help System Sandcastle Roadmap

Henning Krause

Hello Dave,

If they integrate it with Visual Studio they would be bound to its release cylce. Which is approx. 2-3 years. If they keep it seperated, they have at least *the option* for a shorter release cycle.

That said, I do certainly support the idea of integrating in into the GUI - but with some sort of a loos coupling via an Addin or so.

The truth is, I didn't need any sort of integration in the past at all. Every now and then I would just start the SandCastle help file builder to update my documentation....

Henning





Re: Developer Documentation and Help System Sandcastle Roadmap

Dave Sexton

Hi Henning,

Ok, I see your point about a tight coupling with VS's release cycle, but what new features do you want anyway As you say, you haven't even needed integration in the past.

But my point is that right now, you can use Sandcastle to build your API docs. But how do you author your conceptual help topics What if you need a more powerful web interface for your content

These are things that would be welcomed features if Sandcastle were to be fully-integrated into VS using topic designers, etc. Without VS-integration, you also lose out on several features such as source control and ease-of-use (yes, it may be easy now - but inside VS itself it's no doubt easier).

- Dave






Re: Developer Documentation and Help System Sandcastle Roadmap

Henning Krause

Hi Dave,

yeah, you're right, I havent thought much about those conceptual help pages. That would be really nice.

But all that (nice designers, option pages and that stuff) can be achieved with a custom project type.

Like WIX (Windows Installer XML, http://wix.sf.net) does this. And you also get version control this way.

Henning





Re: Developer Documentation and Help System Sandcastle Roadmap

Dave Sexton

Hi Henning,

Ok, I can't do that in my software because the VS SDK is required for custom project types, AFAIK, so I just use custom project templates. They're suitable for now, but it might be nice to have a Sandcastle-flavored project type in the future...

Well, if it comes down to a choice between full VS integration without external support vs. partial or no VS integration with full external support, I guess I'd have to side with you and vote for external support. The community seems to be making up for the fact that Sandcastle is not easy enough to use to be a stand-alone product in its current state, and I'm happy with DocProject for integration into VS, for now Wink

- Dave






Re: Developer Documentation and Help System Sandcastle Roadmap

mogens

I think continuing as a stand-alone download is good. Getting tied to the three year release cycle of Visual Studio won't do you any favors.

In order to ship Sandcastle as a 1.0 you need to:
  • improve the documentation included with the package, The included example is trivial, and has no explanation. Documentation should describe the build process and how to customize it.
  • fix the remaining problems in the styles (language filter not sticky in CHM files most importantly).
  • add support for setting the DocSet without editing the templates, or provide a configurable component to do this.
  • include pointers to tools like SHFB and DocProject in the package, and include sample MsBuild and Nant scripts

Visual Studio integration is not so important for us - documentation is built during the nightly build.







Re: Developer Documentation and Help System Sandcastle Roadmap

Anand Raman - MSFT

Christian,

I agree and you have great feedback. I believe the communit feedback is lound and clear and I will do all my best to keep this as a stand-alone tool.

Anand..






Re: Developer Documentation and Help System Sandcastle Roadmap

Craig Berntson

Don't make SandCastle part of Team System, for the same reasons unit testing was added to VS Pro and nDoc is essentially dead. IMO, a standalone utility is best.






Re: Developer Documentation and Help System Sandcastle Roadmap

GeoffreyK

I'd like to see SandCastle continue as stand-alone utility. Putting it only in with VS or Team System would require some one to have those installed to use it, and we don't always have those products installed on our build boxes (or VMs when we're testing functionality). In addition, only making it available through VS might exclude people from using it, who aren't necessarily using it to make documentation for assemblies, but instead are using for documenting a Developer's Guide setup.