6 ms·

This is a very broad question and it would help if you could follow up with your definition of infrastructure. At Amazon, we would use a variety of solutions t

This is a very broad question and it would help if you could follow up with your definition of infrastructure. At Amazon, we would use a variety of solutions to document the build process, how to set up internal accounts, how to respond to pager calls, etc. Amazon has a custom documentation system, but it isn't a whole lot different than the various WIKIs that are available outside of Amazon. Some of what you see as documentation for AWS [1] are an evolution of internal documents from when the solution was used internally before being made public. My time at Apple was earlier, but the systems were similar. Various internal web sites, files checked into cvs/svn/etc and assorted custom issue tracking tools. I wish I could say there were amazing and magical tools that made documentation easy and painless, but there weren't during my time at Amazon and Apple. There might be some very nice tools available that can traverse and document network topology and services that I wasn't exposed to. Hopefully someone will come along and let us know. [1] https://docs.aws.amazon.com/index.html?nc2=h_ql_doc_do_v https://docs.aws.amazon.com/index.html?nc2=h_ql_doc_do_v

iamevn 5y ago
Same at Google, the most important thing is that the main documentation source internally is just markdown files checked in alongside code that is automatically served on the documentation site. Freshness is encouraged by owners periodically getting bugs to review pages and update a tag indicating the page was fresh as of X date. There's support for writing out diagrams in graphviz dot but people usually just draw them in google docs or some other external program and check a screenshot of that in to be embedded in the page. I'm sure some systems had more automation building documentation out of code directly but usually it's just the simple markdown written manually. There's also google docs which is nicer for quickly iterating and getting reviews but it's much less discoverable and falls out of sync with the system much more easily.

iamevn 5y ago

Same at Google, the most important thing is that the main documentation source internally is just markdown files checked in alongside code that is automatically served on the documentation site. Freshness is encouraged by owners periodically getting bugs to review pages and update a tag indicating the page was fresh as of X date. There's support for writing out diagrams in graphviz dot but people usually just draw them in google docs or some other external program and check a screenshot of that in to be embedded in the page. I'm sure some systems had more automation building documentation out of code directly but usually it's just the simple markdown written manually. There's also google docs which is nicer for quickly iterating and getting reviews but it's much less discoverable and falls out of sync with the system much more easily.