I spent two years trying to do what Backstage does for free

https://stackoverflow.blog/2022/12/21/i-spent-two-years-trying-to-do-what-backstage-does-for-free/

by Amorymeltzer • 4 years ago

159 63 4 years ago

depr• 4 years ago

Why would this be reposted to their blog? They had the same post a few months ago. https://news.ycombinator.com/item?id=32909343

Amorymeltzer• 4 years ago

Weird, the link there has been deleted. Thorough discussion though, folks should indeed head there.

kapep• 4 years ago

There are some comments on this article that are a few month old. To me it looks like they accidentally updated publication the date.

conscion• 4 years ago

See this reply [0], they re-published it as part of a holiday "top 10"

[0] https://news.ycombinator.com/item?id=34083279

Veuxdo• 4 years ago

Author might be earnest, but my goodness does this feel like an ad...

michaelbuckbee• 4 years ago

Is there any actual cost to this? It looks like an open source app with no premium upgrade.

arnvald• 4 years ago

Backstage is introducing premium (paid) plug-ins, they're entering beta stage[0]

0: https://backstage.spotify.com/plugins/

vxNsr2• 4 years ago

Especially the way they pivoted to talking about stackoverflow for teams. Felt like it was coming out of left field.

elijaht• 4 years ago

We used Backstage at a previous company. I was fairly unimpressed- it feels like any knowledge/documentation tool in use at a company where it only works with a lot of discipline to keep it up to date. Curious if others have had better experiences with this

ghaff• 4 years ago

Not Backstage specifically but I think you're describing documentation generally in a company of any size. Some tools are better (e.g. better search) than others. But documentation is something that's (hopefully mostly) correct the day it's created and tends to get less correct over time and may or may not get updated or formally deprecated.

There needs to be a process and probably at least a librarian and even then it's often not obvious. In my experience, a lot of written material gets into the "not quite right any longer but we don't have anything better"--and if you go to update it there's invariably a lot of things that end up getting changed. Not sure I've ever cracked open an old paper or blog post and just changed one thing.

vxNsr2• 4 years ago

Yup, in any midsized+ org you need a librarian if you want your doc/kb to be kept in good shape, that person also needs to have a lot of soft power/people skills to enforce rules and procedures many might feel are secondary to their main responsibilities.

BrandoElFollito2• 4 years ago

I had an idea some years ago to gradually lower the contrast on the doc page until the users get frustrated and raise concerns/tickets/escalations.

bringing it to a normal contrast again requires a review of the documentation and some kind of punishing if someone just clicks "yeah, it is still fine".

I hate outdated documentation, primarily including mine.

joshspankit• 4 years ago

My favourite documentation setup was when we decided to go “documentation first” . The entire team would use the documentation every time, and have permissions to modify as they went. We rewarded the “extra time” needed to open the doc and follow/update process every time. (in reality the ROI makes this an easy choice).

There were even cases of printing off doc pages, writing on them while in the field, and updating the digital version.

And it meant that we operated with “one brain” where the documentation always represented the most current collective knowledge.

It was awesomely effective

dugmartin• 4 years ago

I think having the documentation close to the code it documents does make sense though - otherwise it quickly gets disconnected. You just need to create a culture where approval of any code change should also include change to the documentation in the same set of commits.

nailer2• 4 years ago

Same here. We had a wiki, only 20% of us maintained the wiki, a manager (a great cloud engineer, but less talented as a strategist) added Backstage, they were the only person that maintained Backstage,

jsdwarf• 4 years ago

Doesn't backstage offer auto-discovery of docs, ie create docs folder in repo, throw in some markdown files and everything gets picked up? If so, what kind of maintenance was required?

KptMarchewa• 4 years ago

I think Backstage is better than most tools since it integrates a lot of the functionality in one place. If you have the docs, service map, team data etc in 10 different places it will get worse.

trynewideas• 4 years ago

To a developer, it's unimpressive. To a technical writer with no engineering resources or experience to build their own automation who's used to static site generation or fucking DITA XML, it probably looks like magic, especially the discovery and search parts.

ebiester3• 4 years ago

That's true no matter what. That's the manager's job to enforce the definition of done to include updating documentation, pushing to retire or archive outdated information, and providing a vision and culture of effective documentation. It's not always perfect, but there are tradeoffs in everything.

My last place did a fantastic job in documentation. The culture was established before I was there, and I did bring in the diataxis framework to focus the types of documentation we wrote, but engineers had a good set of documentation to start.

It wasn't all rainbows, but many slack conversations were "I wrote this a few months back - let me know what questions you have."

compacct272• 4 years ago

Whoa hey wait, could you expand on this culture of documenting things? what were the requirements? we desperately need some culture around this, it's been terrible in this remote culture to know what anything is actually about in our codebase

intrasight2• 4 years ago

Good interviewee questions: What's your ratio of technical writers to software engineers? Are their salaries equivalent?

At the best companies that I've worked for, the ration was in the 1-10 to 1-5 range, and the salaries were close.

dalyons• 4 years ago

I’ve worked small and midsize startups for a decade+ and the ratio has always been 1/infinity, ie there are zero dedicated writers :/. How common is what you are advocating for? I guess I find it hard to believe 1/5 or even 1/10 companies exist. (Note: I’m not at all saying that’s a good thing )

paateetee• 4 years ago

after the write up, there was a podcast below, now im confused if its called zish or zee-ess-aech?

https://the-stack-overflow-podcast.simplecast.com/episodes/t...

timestamp 1:46

zamadatix• 4 years ago

I've heard zee-shell (like seashell)/zed-shell most often but I don't think there is any nearly universally accepted way like say bash. I've heard both zish and zee/zed-ess-aitch/haitch before but not as often.

perfect5th• 4 years ago

The existence of oh-my-zsh has always implied to me a common pronunciation that rhymes with "gosh", which is really the only way their play on words works.

e12e• 4 years ago

"She sells csh by the sea shore" - changes to voiced s/z for zsh? ("c/see/sea" to (shining) "zee")?

twicetwice• 4 years ago

I've been pronouncing it as "zeesh" in my head, which works well for me. I think I got that from a coworker? Not sure. Works fairly well with "oh my zeesh" as well, which I like.

Mistletoe• 4 years ago

Why did I confuse this with Backpage…

bloodyplonker22• 4 years ago

Ironically, Backstage is an even more appropriate name for it.

andybak• 4 years ago

Despite this post being dated December 21, 2022, I'm 90% I read this a long time back - 6 months or so maybe.

matkoniecz2• 4 years ago

See https://news.ycombinator.com/item?id=32909343

ezekg2• 4 years ago

Knew it sounded familiar. But why would they republish it? The old post now 404s.

sixhobbits• 4 years ago

I thought exactly the same and was confused by the date. Thanks for the confirmation.

rdonovan• 4 years ago

SO blog editor here (and author of the piece). Sorry for the confusion, we're republishing our top ten posts of the year over the holidays, and I guess y'all picked this one up again.

OJFord• 4 years ago

So what does the date mean? Date last marketed?

Not a great thing to do IMO... by all means resurface the good stuff to the top of the blog, but why change the date? SEO? I don't think there's a good answer?

dagenix2• 4 years ago

Are you planning on fixing the misleading date?

ezekg2• 4 years ago

Since the date is in the URL, you broke old links, and without a redirect at that. You should look into how you "republish" because it doesn't look like you're doing it ideally.

Just some helpful advice. Without a redirect, SEO on the old post will go poof.

ProAm• 4 years ago

Gives new ad impressions with a new date.

grepfru_it2• 4 years ago

Service Now enters the chat...

sbarre• 4 years ago

And everything grinds to a frustrating halt?

fnordpiglet• 4 years ago

I wonder if this is any better. I suspect nothing makes these tasks better.

ehPReth• 4 years ago

More like Service Never: https://sharepointlist.com :)

hwestiii• 4 years ago

Needs better headline.

cudgy2• 4 years ago

“In my previous role, searching for a library or service’s owner involved looking at Google Sheets or maybe asking around in Slack channels that referred me to other Slack channels. It took me sometimes one or more hours just to find an answer to a simple question about another team’s code.”

This assumes that there is an “owner” of the code, but code usually changes constantly with documentation drifting out of date as soon as the code is changed significantly. Seems like a product manager might have some of this information as part of a functional specification for the last major effort, but even this will be out of date quickly.

This whole problem is organizational in origin. A high level living document should be maintained, especially for APIs that are exposed to third parties. Lack of that document is the fault of management. Not sure how another tool solves that problem.

scary-size• 4 years ago

From what I experienced not a lot of code changes ownership over a period of years. Not saying code always stays at its place. But disagreeing that ownership „usually“ changes with code updates to the code. I do get on board that change in ownership is often a reflection organisational change. Change to often and things fall through the cracks.

cudgy2• 4 years ago

I never meant that “ownership” necessarily changes when a small change is made like a game of hot potato. Usually, this is an ad hoc process where the person or people that performed the last major change or wrote the original version are considered to be the “owner” or at the least someone that may have insight into the code. However, typically developers need to accept the reality of figuring out the code on their own since the “owner” may no longer work at the company or they have no recollection of what they wrote 5 years ago.

bamboozled• 4 years ago

This is a really bad title?

ChrisArchitect• 4 years ago

Previous discussion 3 months ago:

https://news.ycombinator.com/item?id=32909343

I spent two years trying to do what Backstage does for free

Related Stories