End-user help files for DevExpress controls and frameworks

10 February 2009

Back at our annual summit in January (it seems so long ago), we had a discussion about documentation, as we do every year. This year was a little different in that, once we had talked about the developer documentation for our products, we broached the possibility of doing end-user documentation. That is, providing help files geared towards those people who use the applications that our customers write.

People learning at whiteboard We've been asked in the past for such end-user help and we've generally said "just copy what you want out of the help files you have". However, that is somewhat unsatisfactory: just the thought of all those customers doing exactly the same thing to the same sections of the help ("here's how to use the ribbon at the top of the window...") is enough to make us wince.

So the documentation team has been doing some work to extract out the relevant information from our existing help files and make it read properly as end-user documentation. Our main goal here is to make it easy for our customers to use these help files in their own documentation. An ideal scenario is when you simply download these help files and use them as part of your application, as is.

  • We've made great efforts to remove all mention of DevExpress (sob, Smile), the names of our controls, Visual Studio, and other "technical/developer/geek" stuff like that from the text. We imagine end-users would be mightily puzzled by such techno-babble.
  • Since we don’t (OK, can't) mention our controls and their options, we can only describe the default or standard behavior. So if you don’t change much when you implement our controls in your app, you won’t need to do much editing of the text or deleting of unnecessary information.
  • We’re thinking of shipping four help files, one for each of the WinForms controls, ASP.NET controls, WinForms XAF applications, and ASP.NET XAF applications. So, if you’re building a WinForms app using all our controls, you can simply include the WinForms end-user help file into your app.
  • We’re thinking of shipping CHM files, which can be easily edited with Microsoft HTML Help Workshop. It’s a free download, you can easily get it here. If you have other software that can decompile CHM files then by all means use it instead.

We need some feedback though. Although we think we've understood the scenarios correctly, we're sure that you'll have some ideas and thoughts that we haven't considered.

  • We believe that providing CHM files will be the best way of deploying this end-user documentation. For those customers who don't want to edit or recompile, it's by far the best solution: download and deploy. I imagine this scenario will be the 80% case. For those that do, however, decompiling into HTML is simple enough to do, from which you can edit and recompile. Thoughts? Are there any other formats you'd prefer instead of CHM files?
  • Although we're thinking of having a comprehensive help file for, say, the WinForms controls, perhaps this would be confusing to the end-user of your app if you haven't used all of the controls we provide. Should we instead have one help file per product, so that there's a help file for XtraGrid, one for XtraTreeList, and so on? This would raise the probability of you having to do some work in editing/stitching the help files together. Is that worse than having to decompile the mega-help-file, remove the text for some control you haven't used, and recompile?
  • All I've been talking about so far is readable documentation. Is it the case that you'd also like screencasts that show off the control for the end-user? The problem I foresee here is that to do this we'll have to create a small app (or just use one of the demos), and that this demo app will look nothing like your app. This may, in and of itself, confuse your end-users more than it helps. (And, no, we don't have the resources to record a screencast just for you Smile.) Thoughts?

We're very close to releasing these end-user help files. Final proofing is going on, and we're readying a new EULA for them, so there's not much time to tell us your thoughts. So let us know today!

Free DevExpress Products - Get Your Copy Today

The following free DevExpress product offers remain available. Should you have any questions about the free offers below, please submit a ticket via the DevExpress Support Center at your convenience. We'll be happy to follow-up.
No Comments

Please login or register to post comments.