incubator-yoko-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Lars K├╝hne <>
Subject Re: Documentation (RE: [DISCUSS] Yoko Graduation)
Date Fri, 16 Feb 2007 06:31:59 GMT
Sakala, Adinarayana wrote:
>> Maybe it would help to have some kind of technical overview document,
>> package docs, and things like that. This would give newcomers a much
>> better chance to reach the level of Rick and the IONA developers.
> This is a great idea.
> What docs do we need?
> 1. Overview Guide
>    - Including corba and webervices usecases.
> 2. Getting Started,
>    a) A step by step walkthrough of a corba demo
>    b) A step by step walkthrough of a webservices demo
> 3. Configuration
>    a) ORB Configuration
>    b) Binding Configuration
> 4. WSDL/XMLSchema to IDL Mappings
> 5. IDL to WSDL/XMLSchema Mappings
> Could be more, Thoughts?
> - Adi

Yes, we need all that end user documentation, but I was thinking more 
along the lines of a design document for the core orb source code. Think 
of a new developer entering the team, what would you tell him on his 
first few days? Sample questions the documentation should answer:

    * What is the purpose of each source package and how do they work
    * Does Yoko provide some plugin points as an external API? Which
      interfaces can be changed without breaking existing clients?
    * Some classes seem to be generated from IDL. Why is it necessary to
      retain the Xyz/XyzOperations hierarchy when the sources are now
      managed in svn and the original IDL is no longer available?
    * Why does the code use a home-grown character set conversion
      algorithm and not nio.charset?
    * Are there areas in the code that you would do differently today if
      you had the time to rewrite them from scratch? Which parts are
      done especially elegant?
    * Is there a way to systematically test interop with other ORBs?


View raw message