Documenting the Imtech SharePoint Enhancement toolkit using Sandcastle
Documentation, Personal, SharePoint, ToolsLast week I have started documenting the Imtech SharePoint Enhancement Toolkit. The toolkit consists of a module which increases the performance of Internet-facing web sites built upon SharePoint 2007 and a module which addresses accessibility and standards compliancy related issues – also in SharePoint 2007 based Internet-facing web sites.
Because we are planning to share the toolkit with the community as a part of the 'Innovation Matters' program (more about the program coming soon) we're busy with since a couple of months, I have decided to document the Imtech SharePoint Enhancement Toolkit: not only the way it should be configured and the way it works, but also the source code.
To document the source I have used Sandcastle: a great tool which produces MSDN-like documentation using reflection and XML documentation embedded in the source code. While installing, configuring the tool and setting up the project weren't that difficult, I have stumbled upon some problems with getting the references to SharePoint types right. Sandcastle allows you to create links to the on-line MSDN documentation to the types from the .NET framework. As SharePoint's SDK is available at MSDN as well, I have decided to use the same feature to create the MSDN links to the SharePoint types used in our code. I have to admit that I haven't succeeded on getting the references right: I was half way there but then I got stuck. Luckily two guys were there to help me out: Eric Woodruff (coordinator of the Sandcastle Help File Builder project) and Dave Sexton. Once again guys: thank you for your help! Eventually I got it right and soon you will be able to have a look at the SDK of the Imtech SharePoint Enhancement Toolkit.
Soon I will post a step by step on how to get the references to SharePoint assemblies right in the help files generated by Sandcastle. Because the code you're writing now seems to be clear and comprehensible it doesn't mean that it will stay like this over a half year or for anybody else who would have to develop on your code. That's why documenting your code is very important and it might even help you to optimize it as you will have to think about what the code exactly does and why it does it that way.
November 6th, 2008 at 4:14 am
You mention in this post that you will soon provide a step-by-step solution to managing SharePoint references with Sandcastle. While I have done this in the past, I was never able to get it to work perfectly. I would be interested to find out more about how you were able to solve the problem.
November 6th, 2008 at 7:36 am
Hi Deavon,
Thank you for your comment. Perhaps I could be of any help before I write the step-by-step guide? I'm curious what your challenges are and what have you already tried.
September 17th, 2009 at 2:57 pm
Hi Waldek,
Is the Imtech SharePoint Enhancement Toolkit still going to be released to the community? Would be great if so.
I'm also keen to pick your brains on a problem I have. We have a heavily customised SharePoint 2007 website which must (and indeed does) achieve WCAG 1.0 AA standards. However in order to achieve this the site users entirely custom controls – no web parts. We've noticed that no search statistics are being generated and have investigated this to the point where we now realise that the SharePoint Search web parts do a lot more than just output the results. They also generate javascript based web service calls that log queries and clickthroughs for the search statistic reports found in the SSP.
I see that accessibility in SharePoint is something that you're particularly knowledgable on. How have you got around this problem? Do you continue to use the standard web parts? Don't they break the AA rule of using tables for layout? Or is there another way to generate the statistics that I'm unaware of?
Thanks for your help with this.
James.
September 17th, 2009 at 9:45 pm
@James: Releasing the toolkit isn't something we're planning to do. Parhaps in the future but not at this moment.
As for the Web Parts: you can fix the tables issue by simply removing them using a Control Adapter. Please note that such Control Adapter breaks the Web Part Page Script Component (WPSC).
In all the WCM solutions I've been working on, I'm trying to use the standard SharePoint functionality unless it's really impossible to do. On the other hand I haven't tried every available Web Part and not all customers require a fully accessible web site.