Kendo UI Documentation and YOU!

Did you know that you can file issues and even make edits to the official Kendo UI documentation? Read on to find out how…

As you’re all no doubt aware, as a part of our Summer release in July, we rolled out a new documentation experience in the form of docs.kendoui.com, an all-in-one site for API documentation, getting-started guides, tutorials and more.

As I stated in the launch Webinar, the move to a new site was another step in the evolution and improvement of the Kendo UI Documentation, as opposed to an “ok, we’re done now!” statement. Kendo UI is still very young (it’s our first birthday already, can you believe it?), but we’ve grown fast, both in terms of customer adoption and features included in the various Kendo UI offerings. With this rapid growth comes a bevy of challenges, not the least of which is making sure that our documentation remains “up to snuff” (or gets “up to snuff,” depending on your point of view) as we grow. To keep pace, we had to kick off some drastic changes to our pre-Q2 docs.

Improving the Kendo Docs Authoring Process

After taking a look at our existing documentation, we grouped needed improvements into three categories:

1. The Authoring Process
2. The Experience
3. The Content

Our old process was time-consuming and painful, and we knew that the very first step needed to “unlock” improvements to both the experience and the content was to improve the authoring process. With this in mind, the largest shift that we made for the Kendo UI documentation last quarter was to move to a totally new authoring process. This change is mostly invisible to you, our customers, but it was absolutely needed for us to quickly evolve our content based on your needs.

As a part of that shift, we decided to author all of the Kendo UI documentation in Markdown (which we are all well-versed in and comfortable with… this very post was drafted in Markdown, for instance) and then generate HTML documents for the new docs.kendoui.com site based on the Markdown content.

The beauty of this setup, in our opinion, is that we can quickly author and modify docs in any text-editor, with no hassle whatsoever. Our docs are versioned in Git, so we get the same level of change tracking and repository management that we already utilize with Kendo UI itself. The end result of this move is easier authoring of docs. And easier authoring means more frequent updates, more docs and the ability to more quickly fix errors and respond to requests for additional content. That’s number three in the list above, and though we’re still in the early phases of having the needed capacity to keep our docs moving and evolving as fast as you need them to, we’re happy that the process itself is ready to respond as we do.

How You Can Help Us Improve the Docs

Of course, as interesting as this “behind the scenes” look at the docs process might be to you, it doesn’t make for a very worthwhile blog post by itself. Rather than continue the navel-gazing, let’s talk about what the improvements to the authoring process mean to you. Specifically, I want you to know that you can file issues and even make edits to the Kendo UI documentation yourself.

I mentioned already that our docs are versioned with Git, just as Kendo is. When we decided to keep our docs in Git and, thus, on GitHub, we also decided to make the repository public and release its contents under an MIT License. The result is the kendo-docs repository, which I encourage you to check out if you haven’t already. Not only can you find the current content of docs.kendoui.com here, but we also maintain branches for as yet unreleased or Beta features.

In addition to making our docs public, the move to GitHub means that you can help us make the docs better in one of two ways. You can either:

1. File an issue; or
2. Make some edits and send us a pull request. (we love pull requests!)

Instructions for both can be found in the Readme for the kendo-docs repo.

No matter how you choose to engage with our docs, we want the authoring process to be more transparent, and that includes giving you a place to tell us what’s missing or incorrect. When you’re working with Kendo and you find something that’s incomplete, confusing or just outright missing, tell us! With such a quickly-evolving framework, oftentimes we don’t see the holes unless you wave them in our faces. Even if you’d rather not propose a fix in the form of a pull request, we’ll gladly accept an issue for the needed improvement.

Where We Go From Here

As I stated above, we look at docs evolution in three ways. This post, and our move to GitHub is about the first, but that doesn’t mean that we’re ignoring the other two. We’re in the process of scaling up our content engine as we speak, and we’ve also been hard at work over the last couple of months on improvements to the experience at docs.kendoui.com. This includes things like adding grouped autocomplete functionality to the site search, added a related documents sidebar to the left nav, and UX improvements to our API docs pages. These will be going live as they are ready in the coming weeks, and we hope that you not only like them, but that they continue to improve your experience with our docs. If not, you know where to go to tell us!