| Wikis end up being a poorly generalized dump of poorly structured info combined with an information discovery problem. What do you want to put in it? How to do things? Runbooks for common problems? Explanations of how systems function? API Documentation? Why not generalize it and make it discoverable. If it's a "how to" it should probably be in the repo in a top level directory. If it's a runbook, why not keep a google doc link next to your alerts? If it's api documentation, I think there's plenty of software for that. If nothing else, why not create a data structure in your repo's top level directory that lists persons, teams, or services and documentation associated with them api_team:
public_docs:
"Public API Doc": "https://..."
"Internal API Doc": "https://..."
important_design_docs:
- "https://..."
- "https://..."
run_book: "https://..."
onboarding_doc: "https://..."
architecture_spec: "https://..."
members:
- jane
- jim
ops_scripts:
- push.py
- rollback.py
- drain_region.py
dashboard: "https://..."
Write a validator so that every team has a link to a runbook...Why invoke an entire service with a database that needs maintenance, security, and some notion of accounts? My question for you is: what do you hope to achieve by setting up a wiki? What can a wiki do that nested google docs can't? |