+1-888-365-2779
Try Now
More in this section
Categories
Bloggers
Blogs RSS feed

Using Sitefinity to Manage Our Own Product Documentation

by Slavo Ingilizov

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.

5 comments

Leave a comment
  1. Rick Curtis May 16, 2012
    Slavo, the new portal looks great and is a huge improvement over the old documentation. I know it must have been a huge amount of work.
    I have a question, and a comment.

    For those of us who manage products it would be great if Telerik would release this as a Module for us to be able to manage documentation for our products. Are their plans to release a Documentation Module?

    Also, knowing that this was a huge migration task, I did notice a few broken links. For example, see http://www.sitefinity.com/documentation/gettingstarted/installation/create-your-first-sitefinity-website and the links on the main body of the page aren't working.

    Congratulations on the new portal.
  2. Slavo May 16, 2012
    Hey Rick,

    Thank you for the nice words. The links have been fixed.

    As for the module - there is no packaged Documentation module. We created everything using the Module Builder and there's no custom code, except the navigation and feedback widgets. This means there's nothing to release, as it's all in the site's database. Once we implement packaging for dynamic modules, we can do it, but until then, you can easily recreate it following the blog post.
  3. Viktor May 16, 2012
    Hi Slavo,

    First of all, the new "skin" looks great, and it's good to hear that your internal projects are being migrated to the Sitefinity 4. Can you please give us an update on what is going to happen to SDK (which I currently can only download from the site) and what is going to happen to existing developer related documentation in the near future? As I understand from your blog post, it is now a lot easier to update the content, so what can we expect in the coming months?

    Thank you,

    Viktor
  4. Josh May 16, 2012
    The SDK will continue to be released shortly after each Sitefinity update. It also includes the old API reference from the site in chm/pdf.

    As for what you can expect, we are constantly adding and updating resources, but please do use the feedback tools on the documentation pages (and of course the forum!) if you have any additional input.
  5. Eitansof Jun 13, 2012
    Hi slavo, Can you please provide more guidelines of how creating this documentation module in sitrfinity? This module is really greate and if you can share the basic action items to create it, navigation tree,template, etc... Thanks !

    Leave a comment