Archived
This forum has been archived. Please start a new discussion on GitHub.
Documentation
Comments
-
What information is missing from our manual, or not presented in a manner so that it is easy to look up? Note that we also have an online reference for the Ice APIs that are defined in Slice.0
-
It's frustration....
It's really just frustration. No matter what you folks say, ICE is
complicated. As Stu Feldman (author of the original 'make')
pointed out, until there was adequate documentation, no one
ever wrote a Makefile from scratch. They took what they had
in hand and modified it until it looked like what they needed;
without really understanding what they were doing. And that
is pretty much what I have been able to do with ICE---take the
Hello demo and crunch it into a sembance of what I want to
test.
The real problem is the lack of a subjective compendium. That
is, the 'manual' uses a "case study". It does not slice the loaf
in the other direction. Is there a chapter/section on what must
and what can go into a config file. Is there a discussion of
names that are necessary and where and how they will be used,
as in "this is an adapter name, it will be referenced by, it is
needed for, it will be used by"?
The 'manual' isn't awful. It fills a need. Though I have come to
dread it. I must have read it four (or more) times now. I know
all about why ICE is better than CORBA. I am a convert. I am
trying to get it incorporated into the next generation of telscope
software. But I cannot sit down and write a program that
uses ICE from scratch. And I won't 'know' ICE until I can.
Different people learn in different ways. I have been writing
programs for, well, a *lot* of years. I teach programming at
a university. And, sad to say, I am struggling with ICE.
In truth, I get much of my useful ICE information from the bits
and pieces of code, the demo programs and such. I print them
out and carry them around. I pour over them when I walk
across campus (and sometimes while I wait at traffic lights).
But it is slow going trying to make associations and inferences
free-form in this way. It is akin to trying to break a code with
very little cipher text to work on.
Thanks for listening.
Titus sends0 -
Hi Titus,
I'm sorry to hear that you are not happy with the documentation. So far, we have had nothing but positive feedback for it--almost everyone seems to be happy with the documentation. Of course, that's not to say that your difficulties aren't real or that the documentation couldn't be improved. It's just that the manual cannot be everything to everyone. And, as you say, Ice, while being a lot simpler than CORBA, has still a fairly large API.
We wrote the manual as a combination of tutorial and reference. You can read it end-to-end but, using the TOC (and especially the search feature of the online version and the online Slice reference), it is fairly easy to zoom in on particular subjects.
If you want to get going with Ice, there is actually fairly little you need to read. For any particular programming language, read- Ice Overview
- The relevant parts of "A Hello World Application"
- The Slice Language
- The relevant language mapping chapters
The remaining chapters (and sections) each deal with a specific topic or feature set, so you need to read these only if they are of interest to your program.
As you say, there are other ways we could have sliced and diced this information. What we settled on we believe to be a good compromise between tutorial and reference (but certainly not the only possible compromise).
As Ice gets more popular, I expect that other people will start to write documentation that tackles the subject matter from different angles. Until then, please do not be discouraged. As you use the APIs more, you will find that a lot of things that seem difficult now will diffuse into the "general knowledge" section of your brain, leaving you to focus on more advanced topics.
As you say, the demos are there to help as well--each demo illustrates a specific technique or part of the Ice API. In addition, I suggest that you browse our newletter articles. The "Article Index" tab presents articles by topic, and you will find many code examples and additional explanations for various programming tasks there.
Finally, the FAQs also answer many questions that our developers have asked over the years.
Cheers,
Michi.0 -
I'm sorry to hear that you are frustrated with the manual. In any case, here are a few hints:Is there a chapter/section on what must and what can go into a config file.
Yes, have a look at this chapter:
http://www.zeroc.com/doc/Ice-3.2.1/manual/PropRef.html#50822Is there a discussion of names that are necessary and where and how they will be used, as in "this is an adapter name, it will be referenced by, it is needed for, it will be used by"?
Yes, we have this in our Slice reference:
http://www.zeroc.com/doc/Ice-3.2.1/reference/0 -
I encourage you to read the newsletter articles in detail. There are quite a few articles covering some pretty basic concepts such as proxies in http://www.zeroc.com/newsletter/issue23.pdf. If you have something specific that you would like to see covered in more detail please let us know!0