Using Sitefinity to Manage Our Own Product Documentation

We just launched a brand new Sitefinity documentation portal, which you can access at http://www.sitefinity.com/documentation. The goals we had for this project were to make all our documentation resources more easily accessible, and provide a single place that you can go for help when using Sitefinity. At the same time, we strived to make it painless for the internal team to ship new content and manage the existing articles. We hope you like the result and would appreciate your feedback. Here’s how we did it using Sitefinity.

Abandon All Obsolete Tools

Up until now, we used different tools to manage our documentation. The user documentation was managed in Sitefinity 3.7, while the developer documentation used the Sandcastle Help File Builder. This created some inconsistencies and slowed down the deployment process. Sandcaslte is a tool that can generate HTML from the comments inside your codebase. However, it falls short when used to write longer articles with various content in them. This is how the edit screen looks like:

You have to use a custom XML-like language called MAML, and write it manually (no intellisense). Not very user friendly.

The other problem was that Sandcastle outputs static HTML files and goes through a build process, much like a software product. This meant we had to wait for hours if we wanted even the slightest change in a topic. If only we had a decent CMS that we could use to manage all this content…

Switching to Sitefinity 4.4

Naturally, we decided Sitefinity was the perfect tool to use. Moreover, with the launch of version 4.4 we had a module builder, where we could easily create custom content types. We started work.

Creating Dynamic Modules with the Module Builder

For each documentation article, we needed to keep the following information:

• Title
• Content
• Video
• Section (the hierarchy of all articles)

So we created a dynamic module with the fields we needed.

We also wanted to have a way for readers of the documentation to submit feedback. We decided to keep this feedback in another dynamic module, and keep the ID of the article to which the feedback refers.

We keep the comments that customers submit, the IP (so that we can block spammers), and the Rating. This feedback is submitted through a custom control that we developed. It makes requests to a service, which creates items in the Documentation Feedback dynamic module using the Module Builder API. When submitting feedback, readers also rate the articles and we use the KendoUI slider for this rating. Here’s how our feedback form looks:

Hierarchical Taxonomies for Section Hierarchy

Our documentation is separated in several guides, depending on the audience. Those guides are organized is sections, which have a certain hierarchy. Since for now dynamic modules do not support hierarchical relations between items, we decided to use another Sitefinity feature which does – hierarchical taxonomies. Creating a custom taxonomy and a classification field in the Documentation Articles module was enough, and we had the same hierarchical navigation that our customers are used to.

We also created a second taxonomy for the “Getting Started” section of the portal. Custom taxonomies allowed us to classify the same content in two different classifications, and have them display differently in separate sections of the site.

Migration

Now that we had a module to manage the content, we needed to import the existing documentation into it. This was a 2-step task. One step to migrate the developer documentation from Sandcastle, and another step to migrate the existing documentation managed in Sitefinity 3.7. For the first task, we didn’t have much choice. Sandcastle uses its own format (MAML) and we just copied all the generated HTML for articles into the dynamic module. However, to import all other existing content in 3.7, we used the Sitefinity migration module.

With little customization to migrate custom widgets on some pages, it did a great job and saved us a lot of time. We can confidently say that all customers who need to migrate their 3.7 sites can do it easily using the migration module.

Conclusion

We managed to completely transfer all Sitefinity documentation into a dynamic module running on Sitefinity 4.4. There were of course tweaks we had to do. We needed permanent redirects for old URLs, custom widget for the feedback, and custom widgets for displaying videos from YouTube. However, the heavy lifting in this project is done by built-in Sitefinity features – dynamic modules, taxonomies, and pages.

We are proud to finally launch this portal and hope you enjoy using it. We learned a lot from this effort, and will apply all those lessons to make Sitefinity better. Most importantly, from now on, we will create and update documentation much faster. We are better suited to react to your needs and feedback, so please share it.