3 ms·
Ask HN: How do you document applications and infrastructure?
I work in a medium-sized enterprise, and while everybody agrees our documentation is inefficient and ineffective, nobody has a solution that satisfies everybody.
We've tried Git, Confluence, Sparx, Word on SharePoint. Typically, it's either too lightweight and lacking features that key stakeholders need, or too heavyweight and key stakeholders don't want to learn it.
Are there any "happy mediums" in this space, in process and tooling?
- billconan 7y agoThis is a problem I’d like to solve. Which one is lightweight and which is heavyweight?
- gwittel 7y agoI've struggled with this too. They all suck with similar failings. I'm driven by two major factors: quality of documentation, ease of contribution. Getting people to care about both is hard enough without tools getting in the way. Off the shelf solutions cause a lot of problems including: * Repeating yourself (quality/accuracy hit, waste of time) * Spending more time formatting vs creating content (consistency hit, ease of contribution) * Spread of information (service repo v wiki v gitops, etc.) * Discoverability of information So far my best proposal is a custom static site (like Hugo) with lots of archetypes/templates, and custom tools to automate things. Git for versioning. In some cases content is data driven -- e.g. API docs, service dependencies, etc. Other content is loosely structured, or free form - e.g. An alert handling procedure is well structured, but general knowledge may be free form. However, some users don't want to write markdown (even ones who code all day), or the context switch from a browser to an external editor is already enough to prevent quick fixes, etc. My ideal solution needs to keep the above concepts in mind and readily bridge the gap between major factors like: service docs, API docs, architecture, infrastructure, runbooks/monitoring, dependencies, etc. I want to keep as much as possible close to the project (even in its repo), and not repeat myself (because one copy will be wrong). An obsolete runbook is useless. It happens so often because of the information spread: a monitor is configured in one place, pointing to a runbook elsewhere. Typically you have to edit/update both. Similarly, a runbook without context is problematic. When a service is down things like: why is this important, what depends on it (or what does it depend upon) are critical. Being able to walk the dependency tree when diagnosing an outage is extremely helpful.