Anyone who has solved a similar problem in this way knows that creating the initial spreadsheet is only the start of the work you’re doing. As more people found it and found it useful, they added their own fields and sheets to it so that it became a massive, sprawling beast. Because a large engineering org has a lot of turnover, promotions, and cross-team movement, this spreadsheet needed to be regularly updated, I just created a quarterly reminder to nag the entire engineering team. (View Highlight)
We had a wiki, but like many wikis, it was poorly organized and poorly maintained. So we decided to spin up a static site in MkDocs. It would pull markdown files from each service repo and automatically add them to the docs site. This seemed like a clearly superior process: keep the docs alongside the code so they’ll be updated together. (View Highlight)
The downside was that the doc files were treated as code. Every change, even typos, had to have an associated ticket, be reviewed as a pull request, and go through the build process (View Highlight)
Anyone who has solved a similar problem in this way knows that creating the initial spreadsheet is only the start of the work you’re doing. As more people found it and found it useful, they added their own fields and sheets to it so that it became a massive, sprawling beast. Because a large engineering org has a lot of turnover, promotions, and cross-team movement, this spreadsheet needed to be regularly updated, I just created a quarterly reminder to nag the entire engineering team. (View Highlight)
We had a wiki, but like many wikis, it was poorly organized and poorly maintained. So we decided to spin up a static site in MkDocs. It would pull markdown files from each service repo and automatically add them to the docs site. This seemed like a clearly superior process: keep the docs alongside the code so they’ll be updated together. (View Highlight)
The downside was that the doc files were treated as code. Every change, even typos, had to have an associated ticket, be reviewed as a pull request, and go through the build process (View Highlight)
