2 Replies Latest reply on Mar 5, 2015 4:19 PM by Ivan St. Ivanov

    [forge-dev] Feedback on Documenting how to create and test a command that creates Java code

    Ivan St. Ivanov Novice

      Hi everybody,

       

      I went a few times through the tutorial on writing Java source Forge

      commands. Great effort! It was about time we have things like this (which

      is more a bad feedback for me, as I wanted to write something like this for

      quite a long time, but I haven't yet done it ).

       

      So, here is some things that I think can be improved:

       

      - Shouldn't the FAQ and the tutorial be separate documents?

      - Where did the UML diagram of the commands type structure go?

      - According to the title and to the introductory paragraphs of the tutorial

      section, a reader would feel that this is a generic paper about writing

      Forge commands in their own addon (something like in the Developing Forge

      section in the HoL). However, it is more about extending existing

      addons with new commands. So maybe this could be stated more explicitly in

      the title?

      - The Metada.name method gets a string which is by convention something

      like "". Maybe it could be explained how

      would this translate on the command line and in the IDE, what are the

      common command groups and what is the convention for the command names

      - I personally need a better explanation about the difference between

      @AddonDeployments and ShrinkWrap.addAsAddonDependenies

      - It would be clearer if the UITestHarness and ShellTest classes and their

      purpose should be introduced right before the test methods that they are

      used in (checkCommandMetadata and checkCommandShell respectively) and not

      in the beginning of the section. Thus the reader does not lose the context

      around those test helper classes at the point they are used for the first

      time

      - In the beginning of the Let's add some business code section you refresh

      the readers about our goal (i.e. to create a constraint class), but not

      about the Forge command that we wrote before the test section. It may be a

      good idea to remind the reader about that as well, so that she does not

      have to scroll up to find what she did so far

      - It would be a good idea to have a few sentences about what is a facet

      before it is introduced for the first time in testCreateNewPayload method

      - There are some typos

       

      I suppose that you can turn reviewing on and I can do myself some of the

      most obvious fixes (like the typos for example), which you can review

      afterwards?

       

      Cheers,

      Ivan

       

        • 1. Re: [forge-dev] Feedback on Documenting how to create and test a command that creates Java code

          2015-03-04 22:47 GMT+01:00 Ivan St. Ivanov <ivan.st.ivanov@gmail.com>:

           

          Hi everybody,

           

          I went a few times through the tutorial on writing Java source Forge

          commands. Great effort! It was about time we have things like this (which

          is more a bad feedback for me, as I wanted to write something like this for

          quite a long time, but I haven't yet done it ).

           

          So, here is some things that I think can be improved:

           

          - Shouldn't the FAQ and the tutorial be separate documents?

           

           

          Yes, that's the idea

           

           

           

          - Where did the UML diagram of the commands type structure go?

           

           

          It's here https://issues.jboss.org/browse/FORGE-2109

          I took it off because it's not what we have at the moment. I've started

          some refactoring so we would end up with a cleaner class hierarchy.

           

           

          - According to the title and to the introductory paragraphs of the

          tutorial section, a reader would feel that this is a generic paper about

          writing Forge commands in their own addon (something like in the Developing

          Forge section in the HoL). However, it is more about extending existing

          addons with new commands. So maybe this could be stated more

          explicitly in the title?

           

           

          Good point

           

           

           

          - The Metada.name method gets a string which is by convention something

          like "<command group>: <command name>". Maybe it could be explained how

          would this translate on the command line and in the IDE, what are the

          common command groups and what is the convention for the command names

           

           

          Feel free to explain it, I didn't know there was such a structure, I

          thought it was just free text (I don't use IDEs, just CLI ;o)

           

           

           

          - I personally need a better explanation about the difference between

          @AddonDeployments and ShrinkWrap.addAsAddonDependenies

           

           

          Yes, I asked a few question to Lincoln and George. Their answer were ok,

          but I would like to have a deeper explanation.

           

           

           

          - It would be clearer if the UITestHarness and ShellTest classes and their

          purpose should be introduced right before the test methods that they are

          used in (checkCommandMetadata and checkCommandShell respectively) and not

          in the beginning of the section. Thus the reader does not lose the context

          around those test helper classes at the point they are used for the first

          time

           

           

          Hum... I don't get it, feel free to update the doc

           

           

          - In the beginning of the Let's add some business code section you refresh

          the readers about our goal (i.e. to create a constraint class), but not

          about the Forge command that we wrote before the test section. It may be a

          good idea to remind the reader about that as well, so that she does not

          have to scroll up to find what she did so far

           

           

          Done

           

           

           

          - It would be a good idea to have a few sentences about what is a facet

          before it is introduced for the first time in testCreateNewPayload method

           

           

          I don't know much about it, so if you have some knowledge, feel free to

          change it.

           

           

          - There are some typos

           

          I suppose that you can turn reviewing on and I can do myself some of the

          most obvious fixes (like the typos for example), which you can review

          afterwards?

           

           

           

          I've added you write access to the doc. Feel free to change/comment/correct

          it

           

          Thanks Ivan for your feedback

           

          Antonio

           

           

           

          Cheers,

          Ivan

           

          _______________________________________________

          forge-dev mailing list

          forge-dev@lists.jboss.org

          https://lists.jboss.org/mailman/listinfo/forge-dev

           

           

           

           

          --

          Antonio Goncalves

          Software architect and Java Champion

           

          Web site <http://www.antoniogoncalves.org/> | Twitter

          <http://twitter.com/agoncal> | LinkedIn <http://www.linkedin.com/in/agoncal>

          | Paris JUG <http://www.parisjug.org/> | Devoxx France

          <http://www.devoxx.fr/>

           

          • 2. Re: [forge-dev] Feedback on Documenting how to create and test a command that creates Java code
            Ivan St. Ivanov Novice

            Thanks, Antonio! I'll take some time during the weekend to fix the low

            hanging fruit

             

            On Thu, Mar 5, 2015 at 2:26 PM, Antonio Goncalves <antonio.mailing@gmail.com

            wrote:

             

            >

            2015-03-04 22:47 GMT+01:00 Ivan St. Ivanov <ivan.st.ivanov@gmail.com>:

             

            >> Hi everybody,

            >>

            >> I went a few times through the tutorial on writing Java source Forge

            >> commands. Great effort! It was about time we have things like this (which

            >> is more a bad feedback for me, as I wanted to write something like this for

            >> quite a long time, but I haven't yet done it ).

            >>

            >> So, here is some things that I think can be improved:

            >>

            >> - Shouldn't the FAQ and the tutorial be separate documents?

            >>

            >

            Yes, that's the idea

             

            >

            >> - Where did the UML diagram of the commands type structure go?

            >>

            >

            It's here https://issues.jboss.org/browse/FORGE-2109

            I took it off because it's not what we have at the moment. I've started

            some refactoring so we would end up with a cleaner class hierarchy.

             

            >

            >> - According to the title and to the introductory paragraphs of the

            >> tutorial section, a reader would feel that this is a generic paper about

            >> writing Forge commands in their own addon (something like in the Developing

            >> Forge section in the HoL). However, it is more about extending existing

            >> addons with new commands. So maybe this could be stated more

            >> explicitly in the title?

            >>

            >

            Good point

             

            >

            >> - The Metada.name method gets a string which is by convention something

            >> like "

            Feel free to explain it, I didn't know there was such a structure, I

            thought it was just free text (I don't use IDEs, just CLI ;o)

             

            >

            >> - I personally need a better explanation about the difference between

            >> @AddonDeployments and ShrinkWrap.addAsAddonDependenies

            >>

            >

            Yes, I asked a few question to Lincoln and George. Their answer were ok,

            but I would like to have a deeper explanation.

             

            >

            >> - It would be clearer if the UITestHarness and ShellTest classes and

            >> their purpose should be introduced right before the test methods that they

            >> are used in (checkCommandMetadata and checkCommandShell respectively) and

            >> not in the beginning of the section. Thus the reader does not lose the

            >> context around those test helper classes at the point they are used for the

            >> first time

            >>

            >

            Hum... I don't get it, feel free to update the doc

             

            >

            - In the beginning of the Let's add some business code section you refresh

            >> the readers about our goal (i.e. to create a constraint class), but not

            >> about the Forge command that we wrote before the test section. It may be a

            >> good idea to remind the reader about that as well, so that she does not

            >> have to scroll up to find what she did so far

            >>

            >

            Done

             

            >

            >> - It would be a good idea to have a few sentences about what is a facet

            >> before it is introduced for the first time in testCreateNewPayload method

            >>

            >

            I don't know much about it, so if you have some knowledge, feel free to

            change it.

             

            >

            >> - There are some typos

            >>

            >> I suppose that you can turn reviewing on and I can do myself some of the

            >> most obvious fixes (like the typos for example), which you can review

            >> afterwards?

            >>

            >

             

            I've added you write access to the doc. Feel free to

            change/comment/correct it

             

            Thanks Ivan for your feedback

             

            Antonio

             

            >

            >>

            >> Cheers,

            >> Ivan

            >>

            >> _______________________________________________

            >> forge-dev mailing list

            >> forge-dev@lists.jboss.org

            >> https://lists.jboss.org/mailman/listinfo/forge-dev

            >>

            >

            >

            --

            Antonio Goncalves

            Software architect and Java Champion

             

            Web site <http://www.antoniogoncalves.org/> | Twitter

            <http://twitter.com/agoncal> | LinkedIn

            <http://www.linkedin.com/in/agoncal> | Paris JUG

            <http://www.parisjug.org/> | Devoxx France <http://www.devoxx.fr/>

             

            _______________________________________________

            forge-dev mailing list

            forge-dev@lists.jboss.org

            https://lists.jboss.org/mailman/listinfo/forge-dev