I spent two years trying to do what Backstage does for free
I am becoming increasingly skeptical that good internal documentation is even possible. I&#x27;ve been working in software development for around 12 years and have _never_ seen it done well and asking around the best I&#x27;ve heard offered up is the equivalent of an internal stack overflow.<p>For a while, I thought that maybe an exception would be having a technical writer on staff but after reading this post I&#x27;m significantly disheartened on that front too. I&#x27;d be interested to hear if anyone on hacker news has experienced good internal documentation and even more interested if any of you folks have experienced anything truly _great_.<p>For my contribution, I&#x27;ve found that documentation fails for a couple of reasons. The first is the burden of correctness. The people who most would like documentation are also the people who most need the documentation and they usually are also the people most likely to be reluctant to contribute to the documentation because they don&#x27;t feel they can accurately represent the information. Imagine someone ramping into a feature and spending a few days reverse engineering how it works, collecting info, etc. Sometimes they&#x27;ll put it up somewhere but a lot of the time contributing partial information feels &#x27;wrong&#x27;.<p>And the second bit I find to be a big reason why documentation efforts fail is just the sheer friction of putting it into the documentation store to begin with. In confluence, for example, if you have a bit of information it can be tough to work out how to categorize it, where in the hierarchy it should go, etc, etc. Or if it&#x27;s a GitHub wiki you want to put it somewhere that it is discoverable but also be careful that it&#x27;s &#x27;correct&#x27; because you don&#x27;t want to break backlinks if it gets recategorized.<p>I&#x27;ve mostly given up on it at this point. Instead, I take detailed personal notes and make them publicly available. It doesn&#x27;t have to be correct because being advertised as personal notes means that it&#x27;s my opinion on the truth rather than objective fact. It isn&#x27;t far away from my codebase, I can just tap a short keybinding in my editor to type my notes or search them and I can link directly from the notes to lines of code in files to jump back and forth. The particular system I use means that if I write a short snippet of code to solve a one off issue (like calling a path helper to derive a URL that I can&#x27;t find in the interface) I can even drop it in a code block and execute it right from my note-taking tool. It isn&#x27;t ideal for sure but I&#x27;ve gotten way farther in having a shareable knowledge base this way than I have in literal years of trying to get a shared, useful documentation store spun up.