-
1. Re: [Productivity] Level 0 - WS Culture
asoldano Oct 15, 2007 4:28 AM (in response to 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 Oct 15, 2007 9:04 AM (in response to asoldano)"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 Oct 15, 2007 9:11 AM (in response to asoldano)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 Oct 15, 2007 9:12 AM (in response to asoldano)I was going to say: "I would not confront" them with acronyms...
-
5. Re: [Productivity] Level 0 - WS Culture
asoldano Oct 15, 2007 9:43 AM (in response to 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 Oct 15, 2007 10:06 AM (in response to asoldano)"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 Oct 16, 2007 3:50 AM (in response to 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 Oct 16, 2007 5:11 PM (in response to asoldano)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 Oct 17, 2007 2:28 AM (in response to asoldano)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 Oct 17, 2007 5:27 AM (in response to asoldano)"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