Using the source as documentation

ctodx
31 July 2008

A common issue we get dinged on is that our official documentation (by "official" I mean, in essence, our help files) is not complete, and that sometimes topics, how-tos and other things are missing. My response to this is: be specific and I can do something about it and get it fixed, but be general and there's nothing I can do but make reassuring noises. (It's like saying the roads in Colorado are awful, well, sure some are, here's the ones I know, but by no means can I extend the specific anecdotes to a general rule.)

Sometimes I point out that our documentation also encompasses the knowledgebase and the support center and the forums. In an ideal world we'd merge all this data into the help so you wouldn't have to use these online services, but there's always more things to document and so this project gets pushed back. Personally I prefer to use a browser and Google to search for information on our own products (the help is completely online and hence indexed by the search engines). Google has changed permanently what it means to search and the rest of the world is still catching up.

Another source of documentation -- and it can be said to be the ultimate source, since it can never be wrong --- is the source code itself.

So here's a specific case that came up this morning on a phone call I had with a customer. He was having an issue with, wait for it, DXValidationProvider. Yeah, I know, you WinForms pros have got this particular component nailed and are nodding your heads sagely, but for me and the customer we were having some issues understanding how it worked.

If you drop a DXValidationProvider onto the form, you can modify how it validates the values of various controls on the form. There's a smart tag for the component and one of the options is to customize the validation rules. Click it and up comes the following dialog.

image

The customer wanted to use the Conditional Validation option. So we clicked it:

image

All very well, but what are Value1, Value2, and Values, and what are they used for? The customer was using "Contains" as the ConditionOperator. He wasn't sure what it really meant but was assuming "is contained in the Values collection" was close and had set up the Values collection accordingly. However he was finding that it wasn't working. Go to the help, is what I said. So we did:

"To create validation rules at design time and associate them with editors, use the 'Customize Validation Rules' editor"

And that, unfortunately, was that, as regards the help. I did ascertain that ConditionValidationRule was the class I should be interested in, but I couldn't find out very much about it in the help.

At which point I went to the source. I pulled up DXValidationProvider.cs and browsed. I found the ConditionValidationRule class and it's Validate method looked like this:

public override bool Validate(Control control, object value) {
return ValidationHelper.Validate(value, ConditionOperator,
Value1, Value2, Values, CaseSensitive);
}

OK, let's take a look at ValidationHelper. It's in the same file. Its main Validate() method (there were a few overloads) was most informative. I won't repeat it here since the lines are long enough to throw off the blog display, but suffice it to say that it consists of a large switch statement on the ConditionOperator value passed in.

Most of the code in each case block  makes calls to another set of methods (EvaluateIsBlankOperator is an example). Nevertheless we don't need to look any further than this to get some helpful information about the ConditionOperator, Value1, Value2, and Values, and in fact to answer the customer's actual problem.

  • Equals: checks the control's value against Value1 to be equal
  • NotEquals: the negation of Equals
  • Between: checks the control's value to be between Value1 and Value2
  • NotBetween: the negation of Between
  • Less, Greater, GreaterOrEqual, LessOrEqual: checks the control's value to be less, greater, etc, than Value1
  • BeginsWith: checks whether the control's value begins with Value1. Both are assumed to be strings. Value1 cannot contain a percent sign.
  • EndsWith: checks whether the control's value ends with Value1. Both are assumed to be strings. Value1 cannot contain a percent sign.
  • Contains: checks whether the control's value contains Value1. Both are assumed to be strings. Value1 cannot contain a percent sign.
  • NotContains: the negation of Contains.
  • Like: checks whether the control's value is "like" Value1, that is, Value1 is assumed to contain a text pattern, and the control's value is matched (or not) against that pattern. Metacharacters are '%' for zero or more characters, '_' for a single character. (Note, to find the metacharacters took more time than I took finding the switch statement.)
  • NotLike: the negation of Like.
  • IsBlank: checks whether the control's value as a string is null or empty.
  • IsNotBlank: the negation of IsBlank.
  • AnyOf: checks whether the control's value is one of the values in the Values collection. If the collection is null or empty, the control's value is assumed valid (this seems wrong to me, so I'll ask).
  • NotAnyOf: checks whether the control's value is not one of the values in the Values collection. If the collection is null or empty, the control's value is assumed valid.

So the basic solution to the customer's issue was to use AnyOf instead of Contains.

Now, let me lay down some thoughts on this small episode. First of all, I agree that this information should be in the help. No arguments from me on that score.

The customer could have pinged our support team with this problem and obtained the same answer, albeit a day later.

And, by the way, I'm certainly not advocating that we don't bother with providing help at all and just ask our support team to always respond with "use the source, Luke".

Nevertheless, with only a short time browsing the source code (less time than it's taken me to write this blog post), I came up with the answer. I hasten to add that I am not very familiar with the source -- it's not like I read a DevExpress source file every night before switching off the light -- but even so, I was able to unblock someone relatively quickly.

So, all I'm saying is, if you're stuck on something, maybe browsing the source is one way to find out the answer. I know it's worked for me with .NET in general; so much so, that Reflector is one of my primary tools.

[General preemptive note: if you find that the help is missing something or is confusing, don't get mad, get even. File a bug report and track it. Don't post it as a comment here: it'll get overlooked or lost. Throw it at the support team, and they'll in turn push it onto the documentation team. Most importantly of all, it'll get registered in our support database and someone will have to do something about it. I won't accept "Accepted - Release TBD" either. Documentation is not code.]

[Another preemptive note: behave if you want to comment, or I will turn off comments on this post faster than a hot knife through butter. This post has all the hallmarks of attracting anonymous ranters.]

13 comment(s)
heather
heather

Your assuming someone would have a requirement for the source code.  We would only require the source code if you were going to go under.

We buy Dx for the productivity not the source code.  Even if we had the source code we wouldn't have them loaded to add more source overhead within Visual Studio plus the fact it would too tempting to make some innocent seeming changes :)

To me it has seemed that the code is getting ahead of the documentation (which is somewhat normal in software dev) however when someone is waiting for a new feature and it finally arrives and then you cannot use it - that is a bit frustrating.

The idea of samples is obviously critical however some of the samples make the learning even more difficult if there isn't sufficient documentation to fall back on.  For example if a sample is going to show dynamic properties then the entire sample should be done in a dynamic manner.  In some of the samples it is 90% static (through the designers) and then only 10% is dynamic and that can be fine if you are only doing that 10%.

I think the videos are going to be the best way to cover ground in a rapid manner and the Dx TV is key.  In fact I would suggest a high priority be placed on deploying videos on the newest features when the feature is released.  It would not only help the immediate adopters but would aid in the sales process as well.

The Dx products are very sophisticated and complex and without thorough docs and samples (btw: Code Central is brilliant) the products can be very frustrating to use.  I would also suggest that the online documentation to be enhanced to have code snippets for nearly all the properties and not just samples copied and pasted.  

I will say for anyone reading this that is thinking about purchase you will most definitely find these products to be better than literally any other product out there - I have used them all.  The support team here is top notch and they are patient with ll requests.

Thanks for the taking the time to hear my perspective Julian - btw I became a big fan many years ago with your Delphi book!

31 July, 2008
Julian Bucknall (DevExpress)
Julian Bucknall (DevExpress)

Heather

You make a good point: to use the source code as documentation in the manner I described, you have to have the source code to begin with (using Reflector in a large "database" of code can be a little tedious because of the auto-generated local member names. etc). Yet a lot of our customers do have the source code (say with DXperience Enterprise), and a lot do buy the individual products with source both for the reason you mention ("OMG, DX is going down!") but also for "reading". I haven't met many who'll admit to altering it though Smile.

I'm really not advocating that source code as documentation is anything but a last resort type activity. Although we do make extreme efforts to name things correctly in the code so that it's readable, it still can't compare to help. Yes, there are areas in the help that need fixing (mine was but a small example), and, by gum, if people report them we'll be fixing them, but equally we can't just drop everything for three months and go find and fix everything.

I'm glad you like the DexExpress Channel and you've hit the nail on the head with what we want to do with it. Our intent is to record, record, record. Everything. All those how-tos in the help? Record and expand on them. A new product coming up? Record a series of videos on it and how to use it. We're getting the workflow down pat now to such an extent that Jeff can whip around a recording and upload it in a matter of a couple of hours. In fact, he's getting so good at it, the bottleneck is now the rendering speed.

Thanks for the thoughtful comment. Always appreciate your viewpoint.

Cheers, Julian

1 August, 2008
CESAR F. QüEB
CESAR F. QüEB

Nice point of views guys.. but i have some suggestions yet.

I think that documentation from DevExpress help, blogs, forums and TV channel are excelents methods to learn some features in a product. Recently I placed a suggestion from my customer room: The use of Bookmarks in all pages that include code or tips respect an specific feature into DevExpress products. Currently only the Code Central allows to the customer tracks some article and the track is available too when some customer place a reply into a post.

Respect the videos..., will be nice that support team implements close captions in the videos... on this way.. non native english customers will be very happy.... (some guys speak very fast)... all the content will be very... very useful.

Regards

1 August, 2008
Julian Bucknall (DevExpress)
Julian Bucknall (DevExpress)

Cesar

We've been talking about at least writing "narratives" or "scripts" that go along with each video as separate text files. I don't think we have the resources to go for full close-captions though.

Cheers, Julian

1 August, 2008
heather
heather

Hi Julian,

If you do make the scripts available please make their contents search able as an option.

I think the idea of close-caption is actually a very thoughtful idea but of course fully understand the resource issue.

1 August, 2008
Brandon Maness
Brandon Maness

Another good option is to use Doxygen to document the entire DevEx source folder. It lays out call structure, inheritance, etc.; and can be compiled into a handy dandy .chm file for quick access and searchable content. You can also download the graphing addon (all of which is free) so you get a visual representation of the classes and their interaction with one another. This also works great to document your own projects as well!

1 August, 2008
CESAR F. QüEB
CESAR F. QüEB

Hi Julian,

Thank you for your answer. Let me say that currently Camtasia from Techsmith (www.techsmith.com/camtasia.asp) has support to add and synchronize the audio with the text implemented as captions. DevExpress was using this excelent software in some videos.

Regards

César

1 August, 2008
Dan Arnold
Dan Arnold

If you are advocating the use of sources to understand the framework, which I agree is necessary, why do you stri the source of all comments?

I think the source would be an even greater asset if it were doucmented.

Its kindof a paradox, you have this rapid application development framework that allows you to build apps quickly/ but due to incomplete and fragmented documentation, the learning curve is rather long.

I think there should be a video series that covers code examples for more advanced topics, like creating new templates, changing the scurity system, etc....

Thanks

Dan

2 August, 2008
Jim Foye
Jim Foye

I'm glad to know I'm not the only one to write irate notes complaining about the docs. Hope you never lose your thick skin, Julian!

So looking at the source is another way to figure out what's going on, another item in the toolbox we shouldn't forget about. Duly noted. But keep working on that help file. :)

Keep up the good work.

3 August, 2008
Alex Hoffman
Alex Hoffman

<rant>

I've always been really annoyed that comments are stripped from DevExpress code. :(

In most projects I'm involved with, the intention of code reviews are primarily to ensure that code is written and commented such that another developer could effectively maintain the code in the future.

That is done because it is generally understood that it is extremely difficult to understand the code written by another developer.  Sure one can look and understand small snippets of code, but understanding the dependencies, interaction and intention behind large complex codebases can be near impossible.

My question is - why do you strip the comments?  Do you see some commercial necessity to remove them?

<rant/>

-- Alex Hoffman

http://expressapp.blogspot.com

3 August, 2008
Julian Bucknall (DevExpress)
Julian Bucknall (DevExpress)

Alex

Phew! Well, OK, in an attempt to be humorous, why do you think we have any comments to strip out? And then in an attempt to be more serious, why do you think that the comments that we may or may not strip out are written in English? (That is, the comments would be written in the native language of the developers.)

Anyway, I'll have to ask R&D. Maybe this was something we did for a reason in the past, but is no longer quite so necessary. Maybe there are discussions in the comments that reveal some rationales for IP. I don't know.

Personally speaking: the above post was written using the source code that our customers get. I don't have a login for our version control system (besides which, I shouldn't have). I do find our code has been written to be quite readable.

Cheers, Julian

4 August, 2008
Julian Bucknall (DevExpress)
Julian Bucknall (DevExpress)

James

Thick skin? Heh, sometimes not so thick. And yes we will continue to improve the help; the post was not an apologia for ignoring the documentation problem.

Cheers, Julian

4 August, 2008
Dave Rowland
Dave Rowland

Without slating the controls, they have been very useful and the amount of information available has been plentiful.  But I am also reflecting on Heather's comments.

As a VB programmer, I have found it very awkward to read back code written in C# and they guess what they mean, what has been extremely useful is finding labs.developerfusion.co.uk/.../csharp-to-vb.aspx to convert the C# to my language.

I spent an awful lot of time writing ASPxGridView, only to find complications on the way, SQL Datasource was my starting point as this is something I had mastered, so I found that SQL was actually not preforming very quickly, so I dumped that to review XPO, however I found XPO to be very complicated to understand for a simple grid purpose, then looked at LINQDatasource which I was new at and found that I had to scrap my normal ways of doing things, this included Stored Procs as a lot of my logic is in these, so I am not struggling to find suitable information on e.QueryableSource within a LinqDataSourceServer

Simple put, I taken an awful lot of time to use a set of controls that have the incentive to 'speed us up' to actually 'slow me down.'  

So I reflect the Calls for:-

Clearer documentation, sometimes one sentance is not very useful, they do need to show some code of some description.

More examples on LINQ, I have struggled to understand why we have very little information on the topic, I would have thought that this was a very important as I have found XPO to be too confusing.

The sleekness and the simplicity of the controls is the reason why we have purchased them, however I have been unable to keep a reasonable development pace with them, so please understand the calls to improve elements of documentation.

8 August, 2008

Please login or register to post comments.