10 Replies Latest reply on Oct 17, 2007 5:27 AM by ropalka

    [Productivity] Level 0 - WS Culture

    asoldano

      This thread is about the first level of productivity efforts we're thinking about for jbossws. Please refer to this http://www.jboss.com/index.html?module=bb&op=viewtopic&t=121127 for a topic introduction.

      Every technology has its own learning curve. Understanding webservices might be not so easy at first because of the number and complexity of all the specification involved. Moreover, the world wide web contains lots of tutorials, guides, walk-through concerning webservice development, but most of them are either hard to understand, obsolete or out-of-date, referring proprietary/non-standard technologies, etc. This is most likely going to mislead and confuse the readers.

      A clear guide providing the right directions for a correct learning path may help users acquire the knowledge they really need without waisting a lot of time. This:
      - increases the user satisfaction
      - gives us customers that really know what webservices are about and use them according to the aims they are meant to be used for
      - finally allows users to easily proceed one step ahead and leverage our advanced features (related to the following levels) for their business, instead of struggling with beginners' issues because of their poor knowledge.

        • 1. Re: [Productivity] Level 0 - WS Culture
          asoldano

          What are we going to do?

          Level 0 issues may be solved enhancing the current documentation. As I previously said, all productivity efforts will start from a reorganization of our documentation. It's supposed to leverage some of the Wiki features, like categories, to link related pages. Our aim will be to provide each user with its own "red-path" for reading the documentation, according to her knowledge and needs.
          In particular, speaking of level 0, beginners will be driven to pages concerning the WS culture, that means:
          - basic webservice knowledge
          - webservices main goals (interoperability, etc)
          - terminology and related technologies (WSDL, SOAP, etc)

          These pages will not go into details, they'll delegate to official third-party docs when needed. They'll only provide the readers with the high level view of a WS system, explaining them what they really have to know. This is going to be something like the glue that keeps the *right* detailed, documentation together.

          The action we think to carry out for this level are quite straightforward; however if somebody has something to add or any suggestion, as always, feel free to comment.

          • 2. Re: [Productivity] Level 0 - WS Culture
            richard_opalka

             

            "alessio.soldano@jboss.com" wrote:
            What are we going to do?
            - terminology and related technologies (WSDL, SOAP, etc)


            Really nice webservices related technologies overview document from INNOQ ;-)

            http://www.innoq.com/soa/ws-standards/poster/innoQ%20WS-Standards%20Poster%202007-02.pdf

            Rio

            • 3. Re: [Productivity] Level 0 - WS Culture
              heiko.braun

               

              terminology and related technologies (WSDL, SOAP, etc)


              IMO people should get to know as much as necessary, but as little as possible. I would confront them with all those acronyms in the first, but talk about contract, payload and endpoint for instance. It will break down to the details soon enough in the subsequent levels.

              The poster is nice, but useless for beginners.

              • 4. Re: [Productivity] Level 0 - WS Culture
                heiko.braun

                I was going to say: "I would not confront" them with acronyms...

                • 5. Re: [Productivity] Level 0 - WS Culture
                  asoldano

                   

                  "heiko.braun@jboss.com" wrote:
                  terminology and related technologies (WSDL, SOAP, etc)


                  IMO people should get to know as much as necessary, but as little as possible. I would confront them with all those acronyms in the first, but talk about contract, payload and endpoint for instance. It will break down to the details soon enough in the subsequent levels.

                  The poster is nice, but useless for beginners.


                  Yes, I agree with you. For instance, when I wrote about the terminology I was thinking about something like -of course I'm over simplifying here- "ok, the service provider publish a service contract describing what it can do; this is written in WSDL, etc". Then we could point to specific resources going deep in details (either on our wiki or external), but the high level view I would provide should be... very high level ;-) Our goal here is only to have the reader understand the fundamentals she can't miss about the webservices and their aims (interoperability etc.)

                  This said, yes, the poster gives a nice view of standards showing how they might be organized (it's now on my desktop ;-) )

                  • 6. Re: [Productivity] Level 0 - WS Culture
                    ropalka

                     

                    "alessio.soldano@jboss.com" wrote:
                    Our goal here is only to have the reader understand the fundamentals she can't miss about the webservices and their aims (interoperability etc.)


                    Sounds like a WikiPedia to me ;-)

                    Richard

                    • 7. Re: [Productivity] Level 0 - WS Culture
                      asoldano

                      Yes, may be. I mean, I think our documentation lacks this and we should somehow have the user acquire this knowledge in the right way. Our wiki is suitable for this kind of communication and we could nevertheless cite or link WikiPedia if it 100% suits what we need. WikiPedia has good contents and will of course be useful, we just need to give the right direction, to draw our "official" line.

                      • 8. Re: [Productivity] Level 0 - WS Culture
                        maeste

                        My two cents about level 0.
                        I think what you are saying would be useful explaining what webservices are, but probably most non-expert users need something clarifying what web service are not. I mean, simplifying a lot of course, something like "web service are not simple xml exchange, are not xml to parse with proprietary sw or read by human" and so on.
                        Another important thing to consider at this level is the target of the docs. Readers would be programmers, but probably also decision maker, IT manager, and maybe QA people who want to understand what they are using. Mainly IT manager (or better people who decide budget ;) ) is an interesting target to get attention and to drive to decide if ws is good for their project. It's also important at this level readers can get the idea and can decide IF ws is a good solution for their environment.
                        IOW you have to inform and evangelize, not to persuade to use ws technology. When readers would take the decision you would have to persuade them to use JBoss stack instead of any others of course, but it is a step forward :).

                        hoping it might help

                        • 9. Re: [Productivity] Level 0 - WS Culture
                          maeste

                          Yesterday night I forgot two important thing I think you should include in docs. Probably they have to be distributed on all levels, but IMHO it's important to have them also at level 0.

                          1) a description of the importance of webservice in SOA. As said probably some IT manager will read your level 0 and it would understand why and where ws would be used. And you know SOA is a great product RH is developing...and a cool buz word ;).

                          2) An explaination of different stack implemented by jbossws. AFAIK you would provide at least native/metro/cxf. Users needs help to select the right one for their goals. Well it's probably mainly a level 1 docs, but some words in this level could be cool to explain to the users the JBoss added value leaving them free to select the best stack for their target.

                          Probably I forgot some others thoughts in this and upper level too..

                          • 10. Re: [Productivity] Level 0 - WS Culture
                            ropalka

                             

                            "maeste" wrote:
                            My two cents about level 0.
                            Most non-expert users need something clarifying what web service are not. I mean, simplifying a lot of course, something like "web service are not simple xml exchange, are not xml to parse with proprietary sw or read by human" and so on.

                            I agree with you, there are many people confused about what webservices are.
                            Many people think its just another XML based RPC method call

                            Richard