Adding Additional Topics Using DocProject

Recently I've been receiving more feedback than usual about the addition of non-API topics when generating compiled help with DocProject (also referred to as custom, additional or conceptual topics). In this blog post I'm going to describe DocProject's current support for conceptual content and my goals for better integration in the future.

Community Feedback

First, I want to say thanks to the users that have emailed me, added feature requests to the issue tracker or started discussions. It's been very helpful.

Special thanks goes to Ben Hall, a computer science student in the UK and also a Microsoft Student Partner (MSP), for his great blog post on how to extend my custom topics tutorial (discussed below in Creating Custom Topics with Partial Builds) to make it work in a more automated fashion.

Ben has also written another blog post on DocProject in which he discusses his experience with DocProject, and for which I have a few responses (a bit-off topic for this blog post though, sorry):

• I know that developers can give up easily sometimes, myself included, when an open source tool doesn't work correctly the first time around. But as you've discovered there can be problems with Visual Studio that I just can't account for in DocProject so patience and a bit of effort is sometimes required to get things going. So thanks for trying DocProject again :)
• You mention that all of the settings are saved in the project.xml file, but actually the settings are saved in the project file; e.g., .csproj or .vbproj. The project.xml file is simply used for the project and namespace summaries (but that will be changing in a subsequent release - I'm going to give each namespace summary its own file.)
• Technically speaking, DocSites don't have a search – they have an index filter. I've already submitted a feature request in the issue tracker for a DocSite search, which I'm currently working on and have been planning for a while now. The indexer and search engine are being written from the ground-up, but are nowhere near completion yet. I also plan to provide an administration screen for managing the index and viewing statistics. The search will be in addition to the filter and will appear in the top-right corner of the DocSite template, just below the link to download the compiled help file.
• The TOC icons, as you mentioned, can be changed easily since it's just an ASP.NET TreeView control. To change the icons open the DocSiteContents.ascx file and change the ImageSet attribute's value from WindowsHelp to Msdn, for example. Maybe I'll change the default in the next release :)

Thanks again Ben! And now back to our scheduled programming…

Custom Topics - But other tools are doing it!

DocProject supports the addition of conceptual content through its partial-build functionality, which I'll explain below. I'm aware that this may not be ideal for most authors.

If you've used other community projects that automate Sandcastle you may have noticed one important difference between them and DocProject: Other tools provide extensions to Sandcastle, such as Eric Woodruff's Sandcastle Help File Builder (SHFB), which apparently has support for additional topics, custom build components such as one that formats code examples, and even patches for some of Sandcastle's presentation bugs. I think it's really great that Eric has done all of that work, but my philosophy for DocProject is different (and no, it's not to slack off ;).

First and foremost, DocProject's purpose is the integration of Sandcastle into Visual Studio 2005 and to expose its core functionality through easy-to-use dialogs and the New Project Wizard. DocProject does not provide any custom build components or bug fixes for Sandcastle, and does not add any additional functionality to Sandcastle's standard build process. DocProject exposes Sandcastle's configuration and transformation files to end-users with minimal changes so that they can customize Sandcastle without being restricted to GUIs, the same as on the command-line without using DocProject or any other automation tools.

A feature that allows users to add additional non-API topics may require a custom build component, custom configuration file or custom transformation files to be shipped with DocProject, possibly breaking DocProject's open-Sandcastle-source policy. In addition, or alternatively, DocProject could make changes to Sandcastle's intermediary files during the help-build process to support the addition of conceptual content, but IMO that would be a hack. Sandcastle already supports conceptual content for Microsoft's internal use according to this blog post – it just hasn't been exposed to the community yet.

As soon as Sandcastle provides a standardized and supported way to include conceptual content in the canonical build process, I'll begin work so that DocProject will support it too.

If Sandcastle goes RTW before providing this functionality, which to be perfectly honest is what I've expected for a while now, then I will attempt to extend DocProject so that it supports the addition of conceptual topics without Sandcastle's support. But let's hope Microsoft realizes how important it is that Sandcastle provides this functionality before it is RTW.

I also plan to offer a Custom Topic Management Dialog that will allow users to manage their conceptual content and even create new topics based on an HTML template, specific for the Sandcastle presentation chosen for DocProjects and DocSites.

Once DocProject fully supports the addition and management of conceptual content it will be a practical solution for generating compiled help in Visual Studio 2005, with designer support, and even without the need to build API documentation.

If you haven't already then hopefully now you see why DocProject does not support the addition of custom topics in the same way as the other community tools.

Creating Custom Topics with Partial Builds

When I first started getting some feedback from the community about conceptual content, not too long ago, I decided to write a tutorial that would help users take advantage of the partial-build functionality offered by DocProject. The tutorial is meant for anyone that uses DocProject, but is especially useful for help content authors that are already familiar with Html Help Workshop's file formats and manually editing them to add additional content. However, this tutorial doesn't describe the end of DocProject's support for custom content, but currently it's the easiest way without having to modify DocProject's code-base.

Partial Builds

To see a partial build in action, load up a DocProject or DocSite and build it as you normally would, but make sure that it will output compiled help (configure your project to produce Help 1.x, for example). After it builds successfully, delete the compiled help file (.chm, for example) and try building the project again. Notice that there is only 1 build step this time since DocProject detects that the file dependencies used to generate the compiled help are still in-tact and that none of the source projects have changed. Only the compiled help file is rebuilt, forgoing the entire Sandcastle build process.

This allows authors to modify the Workshop TOC file manually (.hhc) for the addition of conceptual content and DocProject will just rebuild the compiled help, which will include your changes. If you're using a DocSite template then the DocSiteContents.xml file will be synchronized automatically during a partial build, so your changes to the Workshop TOC will appear in the DocSite's TOC as well.

Conclusion

DocProject does support the addition of conceptual content, but not in the way that most end-users desire or expect since it's not entirely automated. The lack of complete automation is because Sandcastle does not provide a standardized means yet for adding conceptual content, but once it does DocProject will integrate the process into Visual Studio 2005, without hiding the implementation details from end-users. The process should still be flexible and customizable to a certain extent. DocProject, as with several other features of Sandcastle, will provide a management dialog for authors to add, edit, delete and organize their conceptual content. As such, DocProject may eventually be a productive environment for creating and managing help topics and building compiled help inside Visual Studio 2005, even without API topics to be documented.

I'd like to know your thoughts on this so please leave a comment here, start a discussion on CodePlex or contact me using my site's contact form. Thanks!