Ilya,
Just trying to get a sense of what meets your definition of "crystal
clear and concise".
How about this for your steps 4, 5, and 6:
1. Open terminal window and do:
git clone https://github.com/DataTorrent/examples
bash examples/tutorials/topnwords/scripts/newapp
(hit Enter at " Y: :" prompt)
cd myapexapp
mvn clean package -DskipTests
(should have created target/myapexapp-1.0-SNAPSHOT.apa)
2. Go to the Develop page on the sandbox GUI and upload the .apa file.
3. Click the "launch" button to run the application.
For the IDE part, it necessarily increases the size of a document since multiple
screenshots are involved; secondly, each IDE has its own quirks. We currently
do cover NetBeans in the tutorial and are working on covering at least Eclipse
and IntelliJ in the coming weeks.
Ram
On Thu, Nov 19, 2015 at 1:55 PM, Ganelin, Ilya
<[email protected]> wrote:
> Ram -
> I¹ve reviewed the Apex_Development_Setup page and the blog. I am not new
> to Apex, I¹ve built apps in Apex and understand the process but putting
> myself in as a newcomer to the project, given the existing documentation,
> it¹s still really confusing to get started. We¹re presently teaching
> others within C1 how to get Apex up and rolling and getting going from
> ground zero is far from easy.
>
> As a developer, the things that I need to be crystal clear and concise are:
>
> 1) How do I get the codebase
> 2) How do I import the codebase into an IDE
> 3) How do I build and run examples
> 4) How do I create a new project, what do I need to add to maven to do this
> 5) How do I build
> 6) How do I test
>
> At the moment, the documentation doesn¹t paint a clear picture of this.
> The present version is a massive improvement over what was there before,
> but at the moment there aren¹t a few clear steps, with minimal
> configuration and involvement that get a person rolling.
>
> Starting a project or creating a new executable project should honestly
> take no longer than 5 minutes.
>
> With regards to the top N tutorial, if it¹s too complicated to easily set
> up, let¹s have tutorials that aren¹t! A tutorial should illustrate basic
> concepts and be easy to get up and running, otherwise it¹s disheartening.
>
> Does this help clarify a little more?
>
>
>
> On 11/19/15, 11:47 AM, "Munagala Ramanath" <[email protected]> wrote:
>
>>Ilya,
>>
>>Completely agree about starting from scratch. My suggestion to clone
>>the examples repo which
>>contains the entire TopNWords example project was in response to your
>>suggestion in item 5 of
>>your message.
>>
>>For a simpler "Hello World" project, the steps at
>>https://docs.datatorrent.com/apex_development_setup/
>>should work -- it involves running a just a couple of commands on the
>>comand line and, for those wanting
>>an even simpler process, a script is provided that automates things
>>even further.
>>
>>A similarly super-simple approach to gettting started is outlined in
>>my blog: https://www.datatorrent.com/buildingapps/
>>People can directly run many of the existing demos after building core
>>and malhar and then
>>experiment with modifying the sources of those demos.
>>
>>For a more substantial example like Top N Words, there is a fair bit
>>of code needed in multiple files;
>>the process outlined in the tutorial on the website is simply trying
>>to save some time by copying
>>existing files over from Malhar and making the minimal changes needed
>>to incorporate them into
>>a standalone project.
>>
>>For someone wanting to get involved with Apex, I think it is
>>imperative to get familiar with running tools like
>>git and maven from the command line, so the tutorials rely on those tools.
>>
>>Please let me know if you run into problems with any of the above steps.
>>
>>Ram
>>
>>On Thu, Nov 19, 2015 at 11:07 AM, Ganelin, Ilya
>><[email protected]> wrote:
>>> Ram - the use case I'm targeting is having someone create a new project
>>>from scratch based on an example. This is a little bit different. This
>>>is why I was basing it on the documentation from the website.
>>>
>>> The above is a necessity for getting new members involved with the
>>>project.
>>>
>>>
>>>
>>> Thank you,
>>> Ilya Ganelin
>>>
>>>
>>>
>>> -----Original Message-----
>>> From: Munagala Ramanath
>>>[[email protected]<mailto:[email protected]>]
>>> Sent: Thursday, November 19, 2015 01:50 PM Eastern Standard Time
>>> To: [email protected]
>>> Subject: Re: Word Count Tutorial Failure
>>>
>>>
>>> Ilya,
>>>
>>> Could you please clone: https://github.com/DataTorrent/examples
>>> You'll find the complete project in tutorials/topnwords/app
>>> You should be able to build it successfully with: mvn clean package
>>>-DskipTests
>>> I just tried it. Let me know if you run into any issues.
>>>
>>> Ram
>>>
>>>
>>> On Thu, Nov 19, 2015 at 10:18 AM, Ganelin, Ilya
>>> <[email protected]> wrote:
>>>> Hi all I just attempted to follow the instructions here:
>>>> http://docs.datatorrent.com/tutorials/topnwords-c2/
>>>>
>>>> For standing up top N words in Java.
>>>>
>>>> As it stands, things did not work. I was using IntelliJ Idea 14. There
>>>>were a number of issues, a short (not comprehensive) list is below.
>>>>
>>>> 1. There are discrepancies between the selected language level in
>>>>the project settings and certain constructs in the code
>>>> * In WordReader.java diamonds are used, which are only supported
>>>>in java 7 but the language level is set to 5
>>>> 2. The apex version is out of date in the pom.xml file (it¹s set to
>>>>2.2)
>>>> 3. ApplicationWithQuerySupport.java does not compile with newer
>>>>versions of Apex
>>>>
>>>> I spent about 15 minutes trying to get this thing to work in its
>>>>present state and it simply was not an easy and ready to roll example.
>>>>
>>>> General thoughts:
>>>>
>>>> 1. We should not be asking users to manually copy example files from
>>>>one place to another
>>>> 2. We should not be asking them to rename packages to get things to
>>>>work
>>>> 3. We should not be asking them to modify existing example code to
>>>>construct another example.
>>>> * I think a better approach is to provide a complete example
>>>>(that works out of the box) and that we can then walk through line by
>>>>line to explain what it¹s doing.
>>>> 4. We shouldn¹t be asking them to copy-paste in settings. Instead,
>>>>we should walk them through what it means to set settings and have a
>>>>simple enough example that it¹s straightforward to configure.
>>>> 5. Standing up a word count example should be a 1-button-click
>>>>deployment that is ready to run without any user input. Any further
>>>>configuration should only be necessary for the sake of teaching, not
>>>>for the sake of operationalizing the project.
>>>>
>>>> I hope this helps, I¹m happy to offer further feedback. Thanks!
>>>> ________________________________________________________
>>>>
>>>> The information contained in this e-mail is confidential and/or
>>>>proprietary to Capital One and/or its affiliates and may only be used
>>>>solely in performance of work or services for Capital One. The
>>>>information transmitted herewith is intended only for use by the
>>>>individual or entity to which it is addressed. If the reader of this
>>>>message is not the intended recipient, you are hereby notified that any
>>>>review, retransmission, dissemination, distribution, copying or other
>>>>use of, or taking of any action in reliance upon this information is
>>>>strictly prohibited. If you have received this communication in error,
>>>>please contact the sender and delete the material from your computer.
>>> ________________________________________________________
>>>
>>> The information contained in this e-mail is confidential and/or
>>>proprietary to Capital One and/or its affiliates and may only be used
>>>solely in performance of work or services for Capital One. The
>>>information transmitted herewith is intended only for use by the
>>>individual or entity to which it is addressed. If the reader of this
>>>message is not the intended recipient, you are hereby notified that any
>>>review, retransmission, dissemination, distribution, copying or other
>>>use of, or taking of any action in reliance upon this information is
>>>strictly prohibited. If you have received this communication in error,
>>>please contact the sender and delete the material from your computer.
>
> ________________________________________________________
>
> The information contained in this e-mail is confidential and/or proprietary
> to Capital One and/or its affiliates and may only be used solely in
> performance of work or services for Capital One. The information transmitted
> herewith is intended only for use by the individual or entity to which it is
> addressed. If the reader of this message is not the intended recipient, you
> are hereby notified that any review, retransmission, dissemination,
> distribution, copying or other use of, or taking of any action in reliance
> upon this information is strictly prohibited. If you have received this
> communication in error, please contact the sender and delete the material
> from your computer.
>
