incubator-yoko-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nolan, Edell" <>
Subject RE: Documentation (RE: [DISCUSS] Yoko Graduation)
Date Fri, 16 Feb 2007 09:29:55 GMT

It seems that we need a lot of documentation. I don't think this should be left to just one
or two people either. It needs all of the yoko community to get involved across all of the
components. How about we create new Jira issues for these tasks and then people can volunteer
for each one but not have one jira item for each component - I think they should be broken
down even further. I am sure there are several different areas in the orb that could be documented

Cheers, Edell.

-----Original Message-----
From: Lars K├╝hne [] 
Sent: 16 February 2007 06:32
Subject: Re: Documentation (RE: [DISCUSS] Yoko Graduation)

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