[Clojure] Readme: "Getting Started" not entirely trivial to follow

[kohr-h]

I mentioned in #12822 that something in the README of the Clojure package was off and intended to fix it. However, now that I read the text in a bit more detail, I have some broader questions that might be good to discuss in advance before I come up with some random change.

The main issue with the current version is that as someone not familiar with the package architecture and just starting out with Clojure (that's me currently), you just follow instructions and don't really have a clue what you're doing. Some of the nagging questions while doing that were:

• If I want to use prebuilt jars, what exactly do I have to do?

  The fact that some of the instructions I need to follow are under Cloning the repo and running from source is rather confusing. I feel that instructions for "From prebuilt jars" and "From source" should be entirely separate.
  Maybe also good to know would be which possible scenarios there exist. If I should guess I would say (1) everything prebuilt jars, (2) all deps from prebuilt jars, but Clojure package from source, (3-infinity) all possible combinations of prebuilt jars and manual builds for deps, most notably the Scala package and MXNet core.

• Prebuilt jars of what?

  Certainly too much to mention, I guess, but the biggest ones, the Scala package and the base MXNet package would be worth mentioning.

• Where do the instructions end?

  I found it surprising to scroll past the examples to find a header Build from MXNet Source, because "source" was mentioned earlier already. Are those two things connected?
  One way to make it clear that there are two entirely separate sets of instructions (are there?) is to make headers Method 1: Use prebuilt jars and Method 2: Build from source.

• The prebuilt Scala package isn't working ([clojure-package] On modern Ubuntu, scala package cannot be loaded without legacy libcurl #12822, workaround in place now). Can I build it from source but still use a prebuilt jar for MXNet core?

As I mentioned above, I'm not really familiar with the build infrastructure and the Clojure package architecture, so I wouldn't exactly know what to write as instructions. But equipped with some extra knowledge, I certainly could.

[gigasquid]

Thanks @kohr-h for creating the issue. Feedback on the README and getting started is much appreciated and will make it easier for new folks to get started.

Would you be interested in collaborating on this with me to make it better? I was thinking that I could take a crack at updating the README in a PR and then you could give feedback and review it to see if it makes sense and is clearer?

[lanking520]

@kohr-h Thanks a lot for your contribution to MXNet Clojure package. Really appreciated!
Apart from that, I would like to invite you to join our discussion. We have a small group of people working on Scala and Clojure there on Slack, please follow the step here: https://mxnet.incubator.apache.org/community/mxnet_channels.html

I would like to introduce you the basic build procedure for MXNet Clojure package (based on my understanding) @gigasquid please correct me if there is something wrong

1. MXNet backend build from source
2. Make Scala package from source and install it in local system
3. Make Clojure package from source based on the Scala package

@mxnet-label-bot please add [clojure, scala, doc]

[gigasquid]

If you do get on the apache slack - we hang out in #mxnet and #mxnet-scala :)

[kohr-h]

Would you be interested in collaborating on this with me to make it better?

Yeah sure, I'd be more than happy to contribute.

I was thinking that I could take a crack at updating the README in a PR and then you could give feedback and review it to see if it makes sense and is clearer?

That works for me. Probably it's the most efficient way to make quick improvements. But I certainly didn't intend to dump all the work on you @gigasquid 😉

If you do get on the apache slack - we hang out in #mxnet and #mxnet-scala :)

I'll tune in sometime tonight -- which will be afternoon for you I guess? I'm in the Amsterdam time zone.

[kohr-h]

Thanks @lanking520 for the explanation!

[gigasquid]

Great @kohr-h - I have some time for this carved out on Friday so I'll ping you then

[gigasquid]

@kohr-h I have a first draft of it. Please feel free to provide feedback and/or PR's on my gigasquid fork

[kohr-h]

Great, @gigasquid. I had a pretty busy weekend, but I'll have a look at the new version tonight.

[gigasquid]

I think this issue can be closed now that the PR was merged - Thanks @kohr-h