End-user help files for DevExpress controls and frameworks

ctodx
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!

31 comment(s)
Linton
Linton

Looks like a very useful effort Julian, thanks. With regard to the CHM format. If you haven't already, you may want to look into MS's effort to improve the end-user help "experience" by using MAML (Microsoft Assistance Markup Language).  It was introduced in Vista and is expected to be the defacto for Windows 7 and future releases. Because of MAML's context-based approach, you may be able to manage a single set of help source with context-based views for both end-user and developers. It may also provide a simple approach to your second bullet: Should we have one help file per product. Essentially, you'd use MAML to determine the context of the user-initiated help request and present the approprate material. Since you are "very close" to releasing, this may probably be a bit too forward-thinking.

Thanks again, this will be a nice addition to the tools set.

10 February, 2009
Keith Puckett
Keith Puckett

Hey Julian,

The Report Designer has to be the biggest problem my clients have! Any help here would be great!!!!!

10 February, 2009
Neal
Neal

Sounds like a great effort!  The videos would be fine as long as they are "task based training" oriented.  We'll take anything we can get and also be sure to put wherever the legal cops need it that we can plaigarize from this into our own documentation! :)

Thanks again DX, you are ultimately helping us, the developer, which is what it's all about.  

10 February, 2009
Andrew Miller
Andrew Miller

I don't mind a bit of work stitching the files together. I think it would make more sense to my customers.

10 February, 2009
P. Hoogerkamp
P. Hoogerkamp

I am a big fan of DX help files. You guys spoiled me. Now I'm used to DX standard I am always disappointed when using the help files from other third party components. I think it is a great idea if DX would deliver some end-user documentation. I would be a great time saver.

Help files delivered with an application in my experience should always contain far more information than just explaining how a grid or tree works. This means that I always have to write a lot more information myself. I don’t think there are many (if any) application builder that can just deliver help files explaining DX components. Personally  I would never deliver a separate chm file to my customers that just explains DX components and a separate chm file that explains the use of my application. This means I always have to integrate DX topics with my own application specific topics. I add chapters like Working with grids or Customizing reports. In the chapter Working with grids I add topics like Apply filtering, Adding columns, Grouping , etc.

Because of the integration issue mentioned above, I don’t think chm files are the best way to deploy this end-user documentation. I would rather see a set of xhtml files each describing a specific topic (like grouping or reordering columns). This would make it far more easy to only add features that we support. We write our documentation using docbook, so ideally the end-user documentation would be in docbook.

Also the style and appearance of DX topics must match our own. Naturally I cannot expect you guys to format your topics like mine or anyone else’s. Therefore, ideally, DX topics are plain xhml files using only css for styling (or docbook which does not contain formatting information).

Anyway, I appreciate your efforts very much.

10 February, 2009
Robert Fuchs
Robert Fuchs

All this won't help those of us who have non-english speaking customers.

Unless there is a plan to get localized versions of the end-user help files without wasting too much time, resources and money.

IMHO.

10 February, 2009
Julian Bucknall (DevExpress)
Julian Bucknall (DevExpress)

Linton: Thanks for the idea about MAML. Can't say I've ever heard of it, but our Documentation God (aka Vladimir) may have done.

Keith: Heh, that was the "control" that triggered this whole project. No worries there.

P.: Thanks for the compliments! And also your viewpoitn about how we could deply this documentation. We don't use docbook ourselves, so the likelihood of us producing it in that format is virtually nil Sad I'm afraid.

Robert: This is going to be a sticking point, agreed. We have neither the resources nor the time to do this translation ourselves.

Cheers, Julian

10 February, 2009
Anonymous
Phillip Roux

Hi Julian,

Think its a great idea - no mention of VCL documentation? :( As many of the controls will be the same for VCL and WinForms, will you make the WinForms help file available to VCL customers?

10 February, 2009
Anonymous
GlenG

This is going to be a great asset.  I think they definitely should be CHM files and I think that providing them on a control-by-control basis is logical.  

For some controls we may choose to provide the whole help file, but in general I don't see us just 'plonking' it all in ... I see it as an opportunity to speed up our own help file process by incorporating the sections of info that are relevant.

Re screencasts, we've already use links to the dx site when customers needed more info on the layout control (eg devexpress.com/.../QuickStart.xml), so I'm all in favour.    Showing people how things are done in short videos like those on the tv.devexpress site is very often the quickest way for them to pick up a concept and run with it.

10 February, 2009
heather
heather

Nice to see you continuing to improve these areas.  Great job!

Now if you can somehow figure out how to stop VS from taking forever merging new help documents that would be great too!

:)

10 February, 2009
drew..
drew..

Julian, thank you. The xaf docs are an unexpected and *very* welcome treat. All these in any format are more than great. Regardless of how they are presented, there will always be other ideas. Like any great revolution, get it started, hit the ground running and history will show the clear path to take.

10 February, 2009
CESAR F. QüEB
CESAR F. QüEB

Hi...

Great effort guys!...

Do you have a job 4 me?.. I can translate it to Spanish.... and I have experience in Indesign, FrameMaker...Illustrator.. RoboHelp.. and Technical documentation. You know...other job will be welcome in this times.... and with devexpress....

Cheers!

César

10 February, 2009
Geoff Davis
Geoff Davis

Good work guys. This is going to be appreciated further down the line.

P.S. I can translate it to English ;-)

10 February, 2009
Luc DEBRUN
Luc DEBRUN

You have users from all over the world. We should all pitch in for the translations. Let me start ...

Thank you, Merci, Xie xie, aligatou gozaimasu, Gracie, Danke Schon, gracias, shokran, tak ...

Luc

10 February, 2009
Brien King
Brien King

Great work.  I would like to see a priority set on them though...

1. Reporting End User Designer

2. Charting

3. Grids

then what ever else after that....

You can probably skip the controls like TextBox, etc..  If a user doesn't know how to use those, they are in trouble :)

10 February, 2009
Thomas Nielsen
Thomas Nielsen

Here are our thoughts on the subject of help files, or more precisely, what would quite positively grant you a prominent position on our last wills and testaments.

I don’t know how many use Innovasys’ HelpStudio. After all, the Light version was once included with Visual Studio and is now simply endorsed by Microsoft. Anyhow, in HelpStudio it is possible to use what they call snippets. We use them extensively; keeping bits that are updated often or used in more than one location stored in snippets. Edit the snippet and recompile, and everywhere it is used the bit is updated. One wonderful and possibly Nobel prize winning suggestion would then be to do this: Make snippets of every individual control and compile the comprehensive help file from these snippets and offer the snippets as well so we can take one snippet and include it. One might even imagine a scenario with two versions of each snippet, a concise and a comprehensive. The result would be CHM files for those who want them and the snippets that were used for those who want them.

Using snippets will allow us to include a help description in a help project, link it directly into the help file and when the snippets are updated get the latest information by simply recompiling the help file. Can you see how the skies suddenly appear much bluer and the clouds more fluffy?

Regardless what you end up doing your initiative is much welcomed.

11 February, 2009
John Botibol
John Botibol

Great idea Julian, shame about the Report Writer stuff we have spent many weeks on our own version :-)

I guess the best bet would be CHM where it is easy to cut/chop the general help for a control and add it to your own file. Screencasts would be great especially for things like the ReportDesigner (plus XAFised version) where we can add links to your site.

Great stuff and many thanks.

11 February, 2009
Yug Media Resource
Yug Media Resource

Julian, this documentation be exist in Russian language?

If yes, then it's great work!

11 February, 2009
Anonymous
Chris Walsh

Great idea!  This will save tons of time for new customers, as existing ones probably already have a help system already in place.

We use Help and Manual, so .chm would be ideal, as I'd much rather decompile and cut/paste/modify the help docs than come up with it from scratch.

11 February, 2009
Julian Bucknall (DevExpress)
Julian Bucknall (DevExpress)

More comments on your excellent comments:

- we're not planning on translating into any other languages, I'm afraid. We don't really have the resources in-house to do this, and, just like our main documentation, if we did it for one language we'd get inundated with requests for others. Perhaps we'll do the same as we do for the localization dlls: encourage you all to translate and then share those translations.

- we're just talking about the .NET controls and frameworks at present. VCL will be further down the road.

- our plan is to release everything at once, not dribble the files out one by one.

Keep the comments coming if you have some further ideas.

Cheers, Julian

12 February, 2009
drew..
drew..

pleeeeease dribble the end-user report docs immediately as they are ready, pleeeeease. My efforts, and DX, XAF and the RW's reputation have been tarnished because of the 3-year-old blemish with no end-user docs. There is simply no way around this discussion with clients: "Drew, can i get the documentation that comes with the report tool in xaf?", "No. There is none."

pleeeeease. thanks kindly.

14 February, 2009
Keith Puckett
Keith Puckett

I Second Drews request! Please if report Docs ready - Set Them Free!!

Thanks again!!

15 February, 2009
drew..
drew..

hey Julian, before this blog flips to the 2nd page and thus seldom seen again, can you comment on my last post, thanks kindly, drew..

ps: i just had a *major* presentation to a gov't ministry steering committee, with xaf as the central focus. Aside from hardware troubles, things went well, but the lack of end-user reporting docs hit me once again square on the face. The best i could muster was "It is being packaged for release at this very moment".

18 February, 2009
Julian Bucknall (DevExpress)
Julian Bucknall (DevExpress)

Drew: What can I say, without specifying the actual release date (which you know I won't do Smile). Let's see:

- The docs have been proofed.

- The EULA is done (it has to be different than the main EULA).

- Since it doesn't make sense for the end-user docs to be part and parcel of the main install, they're going to be in a separate install. That has to be written, tested, etc. This is in progress.

So, it's close.

Cheers, Julian

18 February, 2009
drew..
drew..

I was thinking about what Max posted:

"We just discussed this topic in a summit session and defined the final date for this. Its internal release date is set to February 10. I can't guarantee we'll include this documentation in DXperience v2008 vol3.4, since the DXperience release is planned for an earlier date. However, you'll be able to request a copy by contacting our Support Dept."

in: community.devexpress.com/.../248106.aspx

and hence my requests for simple access to specific help. This would have gone a long way in front of my audience on Monday.. regardless, thanks, drew..

18 February, 2009
Charles Russell
Charles Russell

Personally I would prefer it in a Microsoft DOC or RTF format or even HTML -  I can make my own CHM files, why not provide it in a "source" file, rather than a "compiled" file. I don't know what you use to create the CHM files and your documentation, but I'd rather have the "source" to make my own version. Then I can integrate it with my help system, not have to waste time "extracting" or "decompiling". And I can make minor edits to fit in to my product...

And, thank you, I've been agitating for this for several years now...

19 February, 2009
drew..
drew..

Let me try this another way: the end-user reporting docs debacle could very seriously lose me a pending significant contract. This is no exaggeration. This sort of thing weighs heavily on the mind of the customer. To get XAF into this gov't ministry could open so many doors. I cannot stress the importance of this issue any more.

Thus, if you could please release just that component NOW, in whatever state it is in, then i can immediately contact the committee and let them know this aggravation is completed as they demand.

25 February, 2009
Anonymous
ctodx

Just a quick note to say that the end-user documentation I promised here a couple of weeks ago is now

26 February, 2009
drew..
drew..

ok.. feedback: the actual effort: A+. I assume the framework docs are forthcoming, but there is no mention of this. Currently only 2 of the 4 files are available. Next: If you have "made great efforts to remove all mention of DevExpress".. then why the full install, dx folders, and dx credits on each page?

thanks again, drew..

27 February, 2009
drew..
drew..

bump. Julian, where do we stand on the framework docs you promised? I have clients waiting based on your comments. Things like this need to be followed through with as we act based on published comments. We can learn to "take it with a grain of salt" and not act, but i believe that is not what you hope to acheive. So please, where are we on this? thank you.

4 March, 2009
drew..
drew..

Another question: this is setup as an installable exe. This simply won't work in many larger organizations that will not allow ANYTHING to be installed willy-nilly. My simple question: i assume i can simply grab the resultant chm's and pass them to my clients, but wonder if i am breaking the revised eula?

4 March, 2009

Please login or register to post comments.