New Java install instructions

[mattheworiordan]

See ably/ably-java#171 and ably/ably-java#161

[mattheworiordan]

@paddybyers @psolstice I do not think the instructions for usage of the library for users for Java & Android is right and needs your input as I do not have sufficient experience with Java to do this.

Firstly, if you look at our README for the Java lib itself, it talks about "Using the library..", then Dependencies, then Building, then Installation (it also used to talk about Tests, I moved this). The Using section tells the user to read the main documentation at https://www.ably.io/documentation.

If you look at the main usage documentation (choose Java in the lang nav) for Realtime and for REST, it loosely mentions Gradle, but has no mention of Android.

Then if I go to https://bintray.com/ably-io/ably which is the bintray link, there is now ably-java, and android, I assume that should be ably-android.

• https://bintray.com/ably-io/ably/android has no README and has the same description as ably-java, and has no versions.
• https://bintray.com/ably-io/ably/Java-WebSocket has no description of readme
• https://bintray.com/ably-io/ably/ably-java has a README (which previously had a download broken link), but doesn't explain anything to do with why there is an Android version etc,
• https://bintray.com/ably-io/ably/core has no README, is on version 0.8.3, and has the same description as android and ably-java

Anyone looking to use Ably in an Android or JRE environment, IMHO, would rightfully be quite confused. We need to please think about making this more user friendly for users in our documentation and in our READMEs, and within JFrog. See https://github.com/ably/ably-ruby, https://www.ably.io/documentation/realtime/usage (choose Ruby lang) and https://rubygems.org/gems/ably as a comparison.

[paddybyers]

The first thing to sort out is the android project and package. Currently android users are still using the java library, which they've been doing since before the restructure, but once we have an android library we should export that.

The package should be renamed to ably-android, and the existing android placeholder package removed.

Firstly, if you look at our README for the Java lib itself, it talks about "Using the library..", then Dependencies, then Building, then Installation (it also used to talk about Tests, I moved this). The Using section tells the user to read the main documentation at https://www.ably.io/documentation.

The first section should be the Installation section, which says what the gradle dependency is. This should be stated separately, as it is now, for Android and java. Then the "Using the Realtime API" and finally the bits about building from source.

If you look at the main usage documentation (choose Java in the lang nav) for Realtime and for REST, it loosely mentions Gradle, but has no mention of Android.

This is because, right now, there isn't a separate Android package, so the java binary is used for both Android and java, and the gradle dependency is the same. But we should fix the Android package and update that section of the docs.

there is now ably-java, and android, I assume that should be ably-android.

yes

https://bintray.com/ably-io/ably/Java-WebSocket has no description of readme

We should populate the package metadata fields in bintray. The project itself has a readme.

https://bintray.com/ably-io/ably/ably-java has a README (which previously had a download broken link), but doesn't explain anything to do with why there is an Android version etc,

This will be taken care of with the updates for the android package once that's been created.

https://bintray.com/ably-io/ably/core

As I noted yesterday, this is just obsolete and needs to be removed.

[mattheworiordan]

@paddybyers @psolstice as far as I can tell this is still not done correctly.

• build instructions still above install instructions https://github.com/ably/ably-java#building
• Mentions Gradle but has no link to JCenter, I don't see why not given it references it from the docs, see https://www.ably.io/documentation/realtime/usage which links to https://bintray.com/ably-io/ably
• I am not sure why we removed JCenter links, see https://github.com/ably/docs/pull/213/files#diff-1ab59b63cab5692046c391b8bacb957fR88 and also in the Readme. Surely we should add this.
• Releases page https://github.com/ably/ably-java/releases is still not set up correctly as per the installation instructions https://github.com/ably/ably-java#release-notes
• Release & JCentre instructions are wrong, https://github.com/ably/ably-java#release-notes, there are broken links
• PR https://github.com/ably/docs/pull/213/files is not resolved and needs merging

[paddybyers]

as far as I can tell this is still not done correctly.

Hopefully these are all now addressed for ably-java and ably-android. I've not done java-websocket yet.

Irritatingly, bintray doesn't support gtihub markdown, so the syntaxt-highlighted code blocks don't work in the readme and they break the formatting. So I've just uploaded a shortened readme for the packages which links to the full one on github.

[paddybyers]

I've not done java-websocket yet.

The Java-WebSocket readme had the same markdown issues so I added a shortform readme directly to bintray.

Unfortuately there seems to be a problem with the Bintray shields, which were all working fine earlier today :(

badges/shields#658

[mattheworiordan]

This has been done now