In the next few days, AWS will start retiring the AWS documentation currently available on GitHub. After reviewing the results of the project and considering the overhead of manually keeping the internal documentation in sync, the cloud provider recently decided to retire most of its public repositories.
Created to increase openness and collaboration, the open-source documentation never gained popularity with the AWS community, with developers lamenting that pull requests were often ignored. Jeff Barr, vice president and chief evangelist at AWS, explains the change:
The primary source for most of the AWS documentation is on internal systems that we had to manually sync with the GitHub repos. Despite the best efforts of our documentation team, keeping the public repos in sync with our internal ones has proven to be very difficult and time-consuming, with several manual steps and some parallel editing (...) the overhead was very high and actually consumed precious time that could have been put to use in ways that more directly improved the quality of the documentation.
Not every repository will be retired, with the ones containing code samples, sample apps, CloudFormation templates, configuration files, and other supplementary resources remaining as primary sources.
AWS made initially available the documentation on GitHub five years ago, inviting interested developers to contribute changes and improvements in the form of pull requests. Barr wrote at the time:
You can fix bugs, improve code samples (or submit new ones) (...). You can also look at the commit history in order to learn more about new features and service launches and to track improvements to the documents.
While some developers will miss the ability to perform a diff to keep track of changes and highlight the reduced options to report issues, others appreciate that AWS finally acknowledges the suboptimal situation. In a popular Reddit thread, some users question if the solution should have been instead to make GitHub the main repository, while others suggest better automation. Corey Quinn, chief cloud economist at The Duckbill Group, comments:
Good on AWS for both recognizing when something isn't working as they'd planned and reversing course, and also for not presenting documentation errors as customers' responsibility to fix.
Ben Kehoe, cloud expert and AWS Serverless Hero, tweets:
I think this is the right decision. I'd love to have properly open and collaborative AWS docs, but in the absence of that, owning up to it is better than the status quo we had.
AWS was not the only cloud provider offering open-source documentation, with Microsoft Azure documentation available on GitHub.