Documentation!
There is hardly any documentation for the C# libraries. For example: See Curve.Rotate function - There isn't a word on the docs. You can try finding other Revolve functions and check their documentation, but then you need to find the right function again. Which is annoying because the parameter names do not appear in the overload lists - And for functions with more than 3 arguments it gets really tricky to find the right overload.
Also, rarely there is more than a 1 line / a few words about each function / parameter. You can never know which exception are raised and what are the possible return values (You get return value = null, and you don't have any way to debug this!). That could be manageable if there was some kind of error reporting you could check - But I couldn't find any.
The tutorials are a joke, and touch very specific issues. FAQs are also 1-liners, but meh. You can almost never find any graphs / drawings / pictures showing anything important. And (maybe I couldn't find it buy) why are we limited to offline documentation? It's easier to google the web and let google get you to the right place.
On the other hand - The code samples are gold (Although I'd be happy to see the code for the Demo project, but no biggie)
[EDIT: The code for the demo project is available, sorry for mis-informing]
This is a pretty advanced library. Many things are definitely NOT self-explanatory - Documentation is VERY important.
Comments
Hi Nitay,
Check your Documents folder and you'll find source code (in both C# and VB.NET) of all the samples including DemoProject.
I think that it would be helpful to have a few lines of code of an example of how it works. Sometimes the syntax listed doesn't make it any clearer to how the function should be used. The parameters in the syntax aren't clearly as to what they actually represent.
As a long time user of Eyeshot I would acknowledge the learning curve is steep, but the reward is great. The guys at devDept can't teach us 3D graphics / modelling, which is what is sometimes required to understand some of the functions and architecture. As you say Nitay, this is an advanced library and it is not meant to teach 3D graphics. It is a wrapper on OpenGL (and now DirectX as well) which hides the really complicated stuff from us, and for that I am thankful to Alberto and his team, it is a really great product.
Thanks so much for pointing this out Damian, as you may guess we currently have no resources to dedicate to documentation authoring.
devDept have done a fantastic job with Eyeshot but without documentation I believe (without exaggeration) that over 50% of the benefits are annulled. It is an extremely important feature, especially for newcomers, that needs to be addressed urgently. It is not about devDept teaching us 3D graphics/modelling as another user above suggested, it is about devDept showing us how their library works.
For example, it took me about two days to figure out in detail how LinearDim works. I use them a lot and I needed to make sure I understood them fully. I had to design a form with lots of buttons that allowed me to play with all the parameters, before I finally understood how they work (in terms of planes, projections of points etc). My final notes were half a Word page that could have been compiled in less than half an hour by an expert at devDept.
We are in a hurry to get the first version of our application out so we have used Eyeshot to an absolute minimum only because we do not have the time to discover its potential out of the code demos, and we know that its potential is far greater than what we have used. I would have liked to include features such as changing the sizes of Entities by dragging vertex points with the mouse etc but I wouldn't dare look into this at this moment given the pressure of time.
Please do not underestimate the power (or the lack) of documentation and urgently include it and complete it in your roadmap. Don't worry about its maintenance or if it goes out of date. It is far better to have an out of date documentation than none at all. Documentation is just as powerful a feature as any of the new goodies that you are working on. Besides us it will also save your support team a lot of time.
PS on comment above: Visual Studio XML documentation is extremely important too. There are a lot of elements that miss XML documentation. Even if you sacrifice detail for easier maintenance it is still far better than not having any. Quick one-liners can very easily capture the purpose and intend of classes, members etc.
Hi George,
We understand your point, of course. We currently try to compensate with our high quality technical support until the company will grow enough to dedicate more resources to documentation. In addition we recently developed two utilities that discover undocumented items so developers can add what it missing.
Thanks for your feedback.
Yep. If you have a problem you need to have solved, you guys really are fast and helpful. Thanks for that, btw.
But sometimes, when I want to find out something under time pressure (and sth. not very "mainstream") and hit a parameter description for say... int Index, with explanation "The index", it can make me rage-quit ^^
But as I couldn't find a real world example in 2 Minutes or so, it cannot be so bad, and actually has improved a lot!! :)
And apart from that: The bang you get for your buck with Eyeshot is great, and quasi-unparalleled as far as I'm concerned and can tell!
I would still prefer more new features(like ensuring the future of our Eyeshot app by targeting .Net Core and separating UI from the geometry core ;) ) over better documentation by a long shot, although I agree with George in principle.
EDIT: Voted for this, anyways
Please sign in to leave a comment.