Using Sitefinity to Manage Our Own Product Documentation

Using Sitefinity to Manage Our Own Product Documentation

January 31, 2012 0 Comments

The content you're reading is getting on in years
This post is on the older side and its content may be out of date.
Be sure to visit our blogs homepage for our latest news, updates and information.

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:

sandcastle

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.

documentationArticlesModule

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.

feedbackModuleFields

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:

feedbackForm

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.

navigation

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.

migrationModule

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.

progress-logo

The Progress Guys

View all posts from The Progress Guys on the Progress blog. Connect with us about all things application development and deployment, data integration and digital business.

Comments
Comments are disabled in preview mode.
Topics
 
 
Latest Stories in
Your Inbox
Subscribe
More From Progress
d12fcc0bdb669b804e7f71198c9619a7
5 Questions Automakers Should Ask to Improve Asset Uptime
Download Whitepaper
 
SF_MQ_WCM
2018 Gartner Magic Quadrant Web Content Management (WCM)
Download Whitepaper
 
What-Serverless-Means-For-Enterprice-Apps-Kinvey
What Serverless Means for Enterprise Apps
Watch Webinar