Documentation objectives

[huntc]

What documentation should we consider? We have been creating Rust doc along the way, and that should provide a reasonable reference, accessible from crates.io. I'm thinking that the regular Akka documentation may also need to include akka-edge-rs.

[patriknw]

I think it should be incorporated into https://doc.akka.io/docs/akka-edge/snapshot/index.html
Your review of that doc site would be useful.

I'm not sure how to exactly structure that, but maybe we can make some of the pages more general so that they work for both JVM and Rust. Then the specifics can be a separate Guide, based on the sample.

This documentation would have to be written in private repo first, so that we don't leak too much before the official announcements, and we have an upcoming release in end of October that will not include the Akka Edge Rust.

[huntc]

I've created a PR for generalising the introduction, which was quite easy to do. The next question becomes one of what we want the Rust example to be... So far, we have the iot-sample in code, with a reasonably comprehensive README. However, it may be nice to also have the team reproduce the edge aspects of the drone example using akka-edge-rs. We have all of the functionality now in place (apart from filters, which I can work on next). I'd then imagine that links/code samples would enumerate Scala, Java and Rust. Alternatively, the documentation could branch at the guide and we could produce a new guide for the Rust iot-service, which I foresee as largely reproducing its README.

Regarding the reference doc, this is automatically published by crates.io when a library crate is published. The one thing we require is to establish the license-file attribute in the Cargo.toml files of each crate: https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields. Rust developers will expect to download and discover crates on crates.io, in a similar fashion to the way Akka is now published to the mvnrepository.com with its BUSL license. I recommend that publishing to crates.io is done at the point of releasing the first alpha so there is easy access to its reference documentation.

[patriknw]

I think we can have a separate guide. If we would use the Drones domain I'm thinking that akka-edge-rs would be running in the drones themselves. However, I think we can stick to the temperature IoT sample domain. Wdyt @johanandren ?

[johanandren]

Sounds good to stick with the existing domain.

[huntc]

Closing as this has now been scoped.