Documentation

titustitus Member Titus PurdinOrganization: University of ArizonaProject: Large Binocular Telescope
Is there any documentation available, other than the 'manual'. An
O'Reilly book would be nice. Yes, I can dig what I need out of the
'manual'; but it is not a reference book.

Comments

  • marcmarc FloridaAdministrators, ZeroC Staff Marc LaukienOrganization: ZeroC, Inc.Project: The Internet Communications Engine ZeroC Staff
    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.
  • titustitus Member Titus PurdinOrganization: University of ArizonaProject: Large Binocular Telescope
    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 sends
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    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
    That gets you 90% of what you need to know. To round out that knowledge, I would read the first six sections of "The Ice Run Time in Detail", as well as the sections on threading models and proxies.

    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.
  • marcmarc FloridaAdministrators, ZeroC Staff Marc LaukienOrganization: ZeroC, Inc.Project: The Internet Communications Engine ZeroC Staff
    I'm sorry to hear that you are frustrated with the manual. In any case, here are a few hints:
    titus wrote: »
    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#50822
    titus wrote: »
    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"?

    Yes, we have this in our Slice reference:

    http://www.zeroc.com/doc/Ice-3.2.1/reference/
  • matthewmatthew NL, CanadaMember Matthew NewhookOrganization: ZeroC, Inc.Project: Internet Communications Engine ✭✭✭
    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!
Sign In or Register to comment.