Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Incomplete
    • Affects Version/s: WW 2.0-beta1, WW 2.0-beta2
    • Fix Version/s: None
    • Component/s: Documentation
    • Labels:
      None

      Description

      Webwork can be difficult for new users to learn at the moment. Better documentation integrated with examples of each feature would help this a lot.

        Activity

        Hide
        matt baldree added a comment -

        We need more specific comments on documentation so we can divide and conquer this beast.

        Show
        matt baldree added a comment - We need more specific comments on documentation so we can divide and conquer this beast.
        Hide
        Peter Kelley added a comment -

        A really good start would be a "Hints & Tips" document that covers ways to do common stuff with code fragments and examples. An example from our curren project would be ways to do forms that have controls in iterated sections in a JSP.

        Show
        Peter Kelley added a comment - A really good start would be a "Hints & Tips" document that covers ways to do common stuff with code fragments and examples. An example from our curren project would be ways to do forms that have controls in iterated sections in a JSP.
        Hide
        Owen Taylor added a comment -

        What I feel is missing is a simple simple simple tutorial.
        I suggest the following as an initial scenario:

        1) Use the existing skeleton-project as a starting point.
        2) Remove any appserver-specific references.
        3) Do not require the use of ant to build it, but instead simply provide it in war-ready (exploded directory) format.
        4) Require and utilize only the functionality present in the bare-bones webwork.jar -do not include any other jar files in the war.
        5) Walk the user through the creation of the formtest.jsp page indicating the expected behavior of each line and the resources upon which it depends ie: the template that will be used and the parameters being passed in each tag.
        6) Explain the properties exposed in the FormTest bean and the validation that is occurring. Have the user provide further validation requirements for the comments field and observe the results.
        6) Provide the views.properties as is and then have the user create a new .jsp page called expression.jsp and change the success mapping to point to that new page.
        7) In the new expression.jsp page, have the user do something simple like this:
        <%@ taglib uri="webwork" prefix="webwork" %>
        <html>
        <body>
        You have reached the expression page indicating success!
        <br />
        Here is your name:
        <b>
        <webwork:property value="user"/>
        </b><p />
        Here is your comment:
        <b><webwork:property value="comments"/></b>
        </body>
        </html>

        This could be followed by more advanced tutorials - each one adding 2 or 3 more gems of webwork magic.

        My 2 cents.

        Cheers,
        Owen.

        Show
        Owen Taylor added a comment - What I feel is missing is a simple simple simple tutorial. I suggest the following as an initial scenario: 1) Use the existing skeleton-project as a starting point. 2) Remove any appserver-specific references. 3) Do not require the use of ant to build it, but instead simply provide it in war-ready (exploded directory) format. 4) Require and utilize only the functionality present in the bare-bones webwork.jar -do not include any other jar files in the war. 5) Walk the user through the creation of the formtest.jsp page indicating the expected behavior of each line and the resources upon which it depends ie: the template that will be used and the parameters being passed in each tag. 6) Explain the properties exposed in the FormTest bean and the validation that is occurring. Have the user provide further validation requirements for the comments field and observe the results. 6) Provide the views.properties as is and then have the user create a new .jsp page called expression.jsp and change the success mapping to point to that new page. 7) In the new expression.jsp page, have the user do something simple like this: <%@ taglib uri="webwork" prefix="webwork" %> <html> <body> You have reached the expression page indicating success! <br /> Here is your name: <b> <webwork:property value="user"/> </b><p /> Here is your comment: <b><webwork:property value="comments"/></b> </body> </html> This could be followed by more advanced tutorials - each one adding 2 or 3 more gems of webwork magic. My 2 cents. Cheers, Owen.
        Hide
        Lars Fischer added a comment -

        You should provide exact examples of the needed directory structure (where to put what), e.g. where to put xslt.

        Show
        Lars Fischer added a comment - You should provide exact examples of the needed directory structure (where to put what), e.g. where to put xslt.
        Hide
        Fernando Martins added a comment -

        One thing I can say as a beginner user of Webwork, is that I was not sure with approach to use (only JSP/only Velocity/JSP + Velocity/XSLT).
        After reading a few posts on the Mailing List I realized that somebody had done some interesting tests with JSP + Velocity, and that probably is something I want to try for myself. But that took much more time searching in the Mailing-list.
        Anyway, my point is that maybe in the documentation should be a section describing the advantages/disadvantages of each of the possible approaches. It would possibly help and give a clearer idea to the beginner user.

        Show
        Fernando Martins added a comment - One thing I can say as a beginner user of Webwork, is that I was not sure with approach to use (only JSP/only Velocity/JSP + Velocity/XSLT). After reading a few posts on the Mailing List I realized that somebody had done some interesting tests with JSP + Velocity, and that probably is something I want to try for myself. But that took much more time searching in the Mailing-list. Anyway, my point is that maybe in the documentation should be a section describing the advantages/disadvantages of each of the possible approaches. It would possibly help and give a clearer idea to the beginner user.
        Hide
        Jason Carreira added a comment -

        This issue is too broad. We've got some more specific items around this.

        Show
        Jason Carreira added a comment - This issue is too broad. We've got some more specific items around this.

          People

          • Assignee:
            Jason Carreira
            Reporter:
            Peter Kelley
          • Votes:
            14 Vote for this issue
            Watchers:
            5 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development