Ask HN: How to write documentation for a medium size engineering org?
I work for a company with ~250 engineers, and one thing that&#x27;s frustrated me is that so much knowledge is shared person-to-person rather than being written down somewhere. A lot of times, the only way to discover things about a new domain is to just know who you&#x27;re supposed to talk to.<p>We have a wiki in Confluence, but it&#x27;s somewhat poorly organized and doesn&#x27;t really have anyone owning its content so it feels useless. We have one large repo and many smaller repos that don&#x27;t have great discoverability, so I don&#x27;t know that a doc directory in our code base makes sense either. Most of the time when I&#x27;m trying to figure out how something works I&#x27;m forced to look in Slack for people mentioning what I&#x27;m working on (and hoping it&#x27;s not locked away in a private channel).<p>I&#x27;m curious to hear what solutions for documentation have worked well where others have worked? And how to &#x27;start&#x27; an effort where I work to better document our various domains?<p>Edit: I&#x27;m realizing that I need to specify: I&#x27;m not primarily interested in documenting APIs, more things like: * Preferred way of doing X * X domain uses these tables and works like this * This is what X feature does and here&#x27;s what it looks like
Most of us work in the single large codebase, and we don&#x27;t have a good separation of responsibility between the pieces yet (it&#x27;s a work in progress) so for now I mostly want to document what stuff exists rather than formal API documentation.