Retiring the AWS Documentation on GitHub
aws.amazon.com
aws.amazon.com
It's a mixture of politics and fatigue.
The vast majority of the Markdown content in these repos isn't the source that AWS Docs works from. Internally, it's a separate content authoring language that is XML-based called ZonBook (though that gets hidden in all but the PDF metadata) that gets run through an XSLT transform. A single user guide can require 4..5 git repos to build.
This means that for any non-trivial change, there is a ton of legwork to re-implement that change in XML, rather than markdown. For some changes, this can be made worse by the ergonomics of the system being less than ideal, and that's for a user guide alone. The process for any sort of API documentation fix is a totally different one built using a different set of tools that have a completely separate build pipeline.
Compile times for some documentation packages can be in the hours. I won't speak for the whole team, but sometimes this just gets grating. The compilation time for one book I worked on was into the two and a half hours for the Markdown output, which was incomplete.
The cause of that incompleteness is that there's a lot of features of ZonBook that don't map to Markdown: XML entities are constantly abused to in lieu of templates and to keep branding correct (for instance, after the [AWS brand in China](https://www.wsj.com/articles/amazon-banned-from-using-aws-lo...) was muddled about, it wasn't as much of a pain in the long run), but also the lack of support for nested paragraphs in tables and arbitrary styling in Markdown puts a bit of a damper on some of the things that writers had been given.
This all culminates in a general lack of interest in moving away to something Markdown derived since there are so many things that don't map to markdown at all that would need to be added for these features to make sense, and lots of these features are essential to the way the docs are managed at a meta level.
I won't get into the general feeling that Legal doesn't trust GitHub (being owned by the largest competitor, there's a lot of speculation about that -- internally there's a "hold Microsoft at knifepoint" sort of opinions that seep out from the edges) and would rather not interact with it at all.
As an AWS cloud Consultant and Instructor, I sometimes find errors in docs and drifts, and would love that community could do a simple PR and fix them. That was not working smoothly because of internal repos and sync, there was no single source of truth (or at least not the public one).
Now what will be the channel to fix the docs? Send something to the other side of the wall that no one is there to catch them? Well, I don’t expect the documentation to be more in sync with less eyes contributing to pinpoint the errors.
I would love that amazon maintains its product documentation so we dont have to do it at our own dime.
That was the problem, no? Fixable without deleting the GitHub repos.
Also, AFAICT contributors never signed over their copyright. Presumably this means Amazon need to keep publishing existing documentation under CC BY-SA (or otherwise, delete all copyrightable third party contributions). What will they do?
Edit: looks like they required copyright assignment (CLAs) for large contributions, so unfortunately they can make the documentation proprietary again.
Having the markdown source for these for invaluable, and so was the Git history, especially for old unsupported releases.
I'm going back to managing my own rack, because logging in to rsync the new versions to S3 and then manually updating my Lambda definitions in the console is too much of a burden for the benefit running my app serverlessly in the cloud as well gives me.
They should fix their process instead of removing the ability to contribute fixes to docs.
Honestly don't know if this is true or not.
The only real complaint majority of people have with aws is price and 95% of the time it’s because they can’t spend 10 minutes doing so math or building their setup right to not cost them.
Curious to hear your specific complaints with GCP.
My biggest complaint on GCP is the support. With AWS when needing support we get responses in 10m to a few hours depending on the severity of the issue. I raised a ticket with GCP about 3 months ago due to a VM vanishing. Could connect to it but not see it in their UI. Took a week to get it back with no explanation. Just magically appeared and ticket closed. Granted our bill with AWS is 25k/m while GCP is about 2k. Thankfully we don’t run production on GCP. Just use it for testing (as we do with Azure)
It sounds like you might be using the free community support that comes with any amount of GCP usage, is that right? Just like AWS, you get community support for free and they offer paid support tiers for a monthly fee with minimum response time for each severity level. If you are paying, the highest response time appears to be one business day. If you are paying for support and didn't get it, that does sound like a serious problem.
Aws service integration would be another thing they do better. The level of service integration is kinda insane.
The whole point of OSS docs is that you empower the community who reads your docs to self-correct them while your skeleton product crew holds the ship down. Now even with ChatGPT, this becomes an even more powerful tool for the average AWS reader to open a quick PR making a doc better.
A huge shame, especially to now overburden your teams directly with low-impact low-quality feedback tickets that could be picked up by the person filing it themselves and completed in minutes.
The feedback popups on the website have no follow-up and if it looks like a memory hole... why would I bother?