I just wanted to say that FlexCel is one of the best software components I've ever purchased. I used it to create 6 reports in Excel format in a week, most of that time just building the datasets I needed to build regardless.And then I added the PDF option. Works flawlessly and fast, 100% managed code, no Excel com objects, in a word, underpriced.
The only thing that needs work is the documentation, but there are so many examples that I've found what I needed there.
Hi,
First of all, thanks for the kind words! We love to hear that our customers are happy with what we do, and well, that is the reason we keep doing it. Every time we hear this kind of positive comments, the day suddenly becomes a little better ;)
About the documentation, of course we keep working on it, but I would like to explain a little how it is organized, why it is organized this way, and what we keep doing to improve it. From many emails I got, sometimes the issue is not the lack of documentation, but that people isn't finding it. So I think an in depth explanation could help.
To give a simple example, the FlexCel .NET setup currently is more than 20 mb, zipped with the maximum compression level. The uncompressed FlexCel.dll is about 2mb, and it is the only thing you really need. The rest is documentation. There is a lot of docs in those 19 compressed mb, as you can expect.
We have organized FlexCel documentation in 4 parts:
1) Concepts. Those are pdf files that speak about how things work, but don't emphasize on "how to" do them. They contain general ideas you should know before using the components, and we try not to keep them too big so people actually reads them.
2) "How to". We consider this a part of the documentation too, but as it deals primary with code, we decided to do this with actual code, not pdfs describing "how to". So we have "demos" that aren't actually demos but ·"examples" on how to do specific things. If I was to do it again, I would make sure they are labeled "Examples" and not "demos", because some people is confused and doesn't realize that this is an important part of the doc (maybe the most important), not really demos to show or help evaluate.
We have structured the examples in a way that you can run them on their own, or from a "demo browser" that shows them all together. Every example comes with an rtf file that describes what it does, how it does it, and why. And we have comments in the code inside too.
But one thing we began to realize when adding more and more examples, is that if you have too much it gets harder to find what you are looking for. We have already over 50 examples, and it is coming to a threshold where we think very careful before adding every new one, because we don't want to bury the demos so you can't find anything.
We did 2 things to make it easier to find those demos: a) We added a "search box" at the top right of the MainDemo app, where you can search for things and find the demos that show them. While I wasn't sure at the beginning if this would work, it is actually quite useful. you can search for tags, words, etc, and it normally finds relevant content. b) We added a "featured" section to the MainDemo app, that just links to the "real" examples, but allows you to decide what's important and what isn't that much.
3)Reference (FlexCel.chm or F1 in Visual Studio) This describes every single method and property available in the pack. Different from the "conceptual" docs, these are specific to a method, and mostly answer the question "what does property zzz really do?" and also tells caveats about a particular method.
As always in FlexCel docs, we try to minimize what we say. "too much" documentation is as bad as no documentation, and actually the best is methods and properties that work as expected, so they don't really need to be explained. Normally when adding doc for a new method/property, we find ourselves writing something among the lines of:
"Beware of this special case: If you have this condition and this condition this method behaves differently"
In all of these cases, I try to modify the method so that remark isn't necessary. Whenever the description of a method gets too complex, it is a sign that the method isn't really intuitive. So we modify the method to be able to make its doc shorter.
4) Tutorials. This is an area I plan to expand in the future, but right now we have some videos online at http://www.tmssoftware.com/flexcel/tutorial.htm
My idea is to add some html (not screencasts) tutorial here too. Any idea in what you Or anybody reading this post) would like to have covered would be very interesting. Hell, if someone wants to write a small screencast or html tutorial on something they find interesting, I would surely appreciate it a lot ;)
So those are the 4 main areas.
But this is just the main topics. We are always adding new things to try to make things easier. For example, we found that a "getting started" document that says more or less what I say in this post could help, and so we added it.
We also have tools like APIMate (which will convert an xls/xlsx file to C# or VB code) that while are not strictly "documentation" are also of a great help when you need to use the API.
And as said, one big concern right now is making the docs more usable. When adding new methods, make them work as intuitively as possible so you don't really need to read the docs to use it. Studying that every new example we add really adds value, and not just adding thousands of examples more so you can't find anything. Searching for new creative ways to help, like the APIMate tool or the "search box" in the examples.
And I look at the inability to find information as a real issue. When someone emails me asking "how do I change the format of a cell?" (and some people do, but luckily not many), I don't think: "well, this is mentioned in the conceptual pdfs, it is in the "Getting started" example, you can easily solve it with APIMate too". I think that something is still wrong and keep thinking how we can make it better. If the information is there, but people doesn't find it, then there is a problem with the documentation.
But truth also remains that FlexCel is a complex suite, it does a million things, and so, it does have a learning curve. We do the most we can to keep it usable, but I won't lie and say it is trivial to use. And you might have issues from time to time that you can't solve, and that's why we provide this forums and the email support.
wow, this got a lot longer than what I expected :) I will stop here, but as said, any ideas (from you and from anyone reading this post) on how to improve docs are always really welcome. We can make use of more ideas ;)
Regards,
Adrian.