Join GitHub today
Meta: Ideas for consolidating and improving documentation #904
Hi! This is just me thinking aloud on Rusoto documentation and looking for a bit of feedback on my thoughts. I'll try to add to this over the next days, but would appreciate some early feedback!
Currently, Rusoto documentation lives in many different places, which can be confusing for newcomers:
Some of the documentation is written manually and at risk of getting stale or out-dated.
For example, the Rusoto gitbook includes a section on the supported AWS services, which has to be kept in sync manually.
Also, there is no automated testing for example code being published in the source code documentation, the git book guides, or the guide on @matthewkmayer's blog. This means that due to breaking changes code could stop compiling without visibility into the issue.
Ideas for Improvement
Thanks for the great write up on this. This is totally something we've needed for awhile (as each you mentioned pretty much has been talked about in an existing issue: #754 , #747 , #685 , #670, #669, #318 ).
I do like having it all in one place though. I think a good first step would be getting on docs.rs, and aws creds in travis (something we need to lower build times for because travis can get creds now).
The rest sound like good ideas, but I think those can wait a bit. That's just my opinion though, I'm curious what would you like to see get done first?
Yes, thanks for bringing this all into one spot!
I've recently updated the rusoto.org source to remove stability tags from services in order to make automating the supported services list easier. However, we haven't had much action in that area yet.
The biggest bang for our buck is probably having our sample code run. We have some locked-down AWS creds in Travis for SCCache ( #833 ). Being able to ensure the DynamoDB sample in our README runs would be
If I could wave a magic wand and have one thing, a comprehensive https://rusoto.org site would make me really happy.
referenced this issue
Jan 3, 2018
Just to create some visibility here, @jonhoo has recorded a great live-coding video where he's using Rusoto to spin up EC2 spot instances.
Watching the part where Jon was integrating Rusoto made me cringe a lot (to be clear, entirely not his fault) due to all the problems he ran into with our documentation.
The YouTube link to jump to the beginning of the Rusoto part is here: https://www.youtube.com/watch?v=Zdudg5TV9i4&feature=youtu.be&t=2190
The video is worth a watch and I think does an excellent job at shining an even brighter light at some of the pain points with our current documentation setup, and should help us understand better where we can improve.
I'll try to find the time later to provide a written summary of the roadblocks from the video.
I'm strongly considering relying on docs.rs for published docs. It's accurate for our published crates and lets of skip doc generation in Travis, which is a big contributor to our slow build times on the stable Rust on Linux build. We should verify they look as expected first since we do some massaging of docs from botocore.
Sounds good to me!
This will also remove the problem of the published documentation being generated from the master branch instead of the latest release.
I still have that branch where I attempt to do conversion of the weird AWS documentation format into proper Markdown, which might improve the formatting and help us get rid of the
Maybe we could also consider contributing a feature to docs.rs to group certain crates (maybe based on workspace?) to improve the discoverability, but I'm not sure how that could look like yet.