My parents owned anf ran a jewelry store for 35 years, nearly their entire working life. My Dad was a master jeweler, goldsmith, sculptor. Among many things, they would string and re-string pearls for folks. Usually family heirlooms that they wanted to keep, but also be able to wear and not fear they'd break and fall all.over the floor. After years of doing that, and also buying raw oearls from overseas, stranding them, and then selling them, my Dad asked the supplier, do yoi guys do stranding? Yes, yes they did, for free. He could have been ordering pre-strung pearls for the same price the whole time. Stranding pearls takes time.
I am becoming increasingly skeptical that good internal documentation is even possible. I've been working in software development for around 12 years and have _never_ seen it done well and asking around the best I've heard offered up is the equivalent of an internal stack overflow.

For a while, I thought that maybe an exception would be having a technical writer on staff but after reading this post I'm significantly disheartened on that front too. I'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_.

For my contribution, I'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'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'll put it up somewhere but a lot of the time contributing partial information feels 'wrong'.

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's a GitHub wiki you want to put it somewhere that it is discoverable but also be careful that it's 'correct' because you don't want to break backlinks if it gets recategorized.

I've mostly given up on it at this point. Instead, I take detailed personal notes and make them publicly available. It doesn't have to be correct because being advertised as personal notes means that it's my opinion on the truth rather than objective fact. It isn'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'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't ideal for sure but I'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.

My company - roadie.io - offers SaaS Backstage. We're the second largest contributor after Spotify and we're co-hosting the first ever BackstageCon at KubeCon NA this year.

Get in touch if you ever want to discuss Backstage. Email in bio.

The main problem with Backstage (BS) is that while it does provide some canned functionality, any extension of that functionality requires the utilization of their plugins system and wholesale buy-in to their ecosystem. Welcome to Wordpress for enterprise developers folks!

The plugin system isn't bad - but its a false narrative to believe you plunk this down and get some sort of valuable developer portal at an enterprise level (small biz sure - fortune 500...yeah no).

Spotify does open-source a number of their plugins, but after having looked extensively at which ones they make available and which ones we would have to write (and deal with their plugin system for) we opted out. The cost/benefit ratio is definitely there for a technical writer, but IMO its not there for serious development. (Pls - Anyone who disagrees with that - begin by telling me why you don't use Joomla as a base for all your custom applications )

Team integration at a company level is another challenge with Backstage. GitHub (the basis and sort of harvested DB for BS) is largely disconnected from company structures and AD and all the things for most companies. Yes GitHub enterprise is a thing... no in general its still not connected to company structures. There are teams in Backstage, but they are generally managed in isolation from the rest of the company which presents its own challenges and integration problems with other systems. Don't even get me started on the fact that asking everyone to put their service defintions in specific files in specific places in GitHub is no better/worse than making them enter it into a ui or spreadsheet or confluence article or anything except now its scattered in 10,000 repos - good luck getting everyone to change that.

Ultimately this isn't software that you simply install and use. Its a base that will likely require extension, and doing so means going down a one way path of adoption. Nothing it does is compatible with anything else. Is that good for Spotify - sure. Lots of folks helping build software they want to use is great. Is it good for the community? I'm not so sure. This article felt like a paid add (not suggesting it was - just saying it read like one) more than an honest plus/minus of the software and is anyone really surprised a technical writer couldn't build a proper enterprise developer portal by themselves? In other news - water is wet, the sky is blue and my kid wants to watch youtube.

The real gem highlighted by backstage is the MkDocs Material theme: https://squidfunk.github.io/mkdocs-material/ It's seriously awesome and has a lot of nice customization options. Out of the box it makes very clean and professional technical docs from a pile of markdown files. Even if you don't need to go the whole backstage route, seriously consider using mkdocs and the material theme.
This is great, and I think if it was fully adopted initially in greenfield, this would be a completely feasible solution. My question is though, these problems exist at large organizations and will be seen as "another tool to rule them all" synonymous with things like "sharepoint". Disclaimer: I'm not saying that backstage is anyway comparable to sharepoint except that it presents itself as this grandiose solution to all things on boarding and learning on your own.

With that said, what's the low hanging fruit to entice adoption of backstage into an organization that already has a "process" like mentioned in the article of whiteboard meetings with stakeholders. Obviously that's not a great use of time, but it's also no extra learning or work, that SME can talk about their function without any preparation and can interactively answer any questions the learner asks at the time.

That doesn't scale in practice, but it also doesn't require any more whole team buy in

> So when I had questions, I needed to track down who owned the service, where their code lived, where their Jira ticket project was, which Slack channel they lived in, and where in the wiki their internal documentation was. Keeping track of this for 100+ services was a pain, so I ended up creating a spreadsheet. It turns out that everyone else in the org needed this information, so this spreadsheet that I created for myself became the document of record for services.


Solving this problem is why I started OpsLevel [1] a few years back. Everyone always starts with a spreadsheet because they're flexible.

But spreadsheets quickly fall apart because they're not complete / up-to-date, automated, or really scalable.

We figured we could automate a whole lot of collecting service info from different places (Git, k8s, other deployment streams) and keeping it up-to-date.

[1] - https://www.opslevel.com

Unrelated to the discussion, just wanted to comment on Backstage's tagline:

“Build an ecosystem, not a wilderness"

which is ironic because a wilderness is arguably the most complete and perfectly functioning ecosystem you're gonna get.

It's hard to infer from some quick documentation-reading whether kubernetes is required to enjoy a lot of the described benefits. Feels like a big first step: "Adopt kubernetes." Having been at a medium-sized org leaning into kubernetes, I can see the draw of a system like this, especially for non-IC roles.
I also really dig the approach of Backstage but found maintaining the installation a real pita. They even give you a tool that tells you which lines have to be manually updated in your installation when updating (https://backstage.github.io/upgrade-helper/).
(Shameless plug) Cofounder of OpenContext.com here. We're a bit different than a developer portal or services catalog, we're a complete context graph of all the assets in your product pipeline. Everything from products, documents, microservices, codepaths, vulnerabilities, people, teams, etc and the relationships between them. The complete context for DevSecOps. Check us out.
Has anyone done this sort of thing for data, not just for services?

I can't seem to find a data catalog that lets my tie information across databases + APIs + Kafka topics. Each catalog of schemas is separate with no way to link them really.

His org used jira but not confluence? Why couldn't they just document these things in confluence?

Edit: This is a serious question. What is that value prop of backstage over confluence?

You would think a writer would know how to write a less grammatically ambiguous title.
Is there a term for this phenomenon, my dear Watson?
Backstage is a well-known entertainment-industry site and publication. What's the motivation for trying to duplicate it?
Curious, I just started a project to integrate Backstage at a Fortune 500, with > 10000 repositories. It does seem like a good foundation so far. Their idea of what it’s supposed to accomplish internally is mostly the same as what this blogpost describes.