CipherThrowaway

FWIW, some version of your rant occurs in almost every industry. Even doctors have hospital administrators complaining about how arrogant and non-business minded they are, how they are opportunistically defending their turf and so on. What you're talking about is not specific to devs but a general symptom of politics and friction between the different layers of an organization.

Devs always lean more cynical than the rest of the org, but the "prima donna devs refusing to acknowledge the need to deliver" schema only emerges in poorly managed organizations and teams. There is always some push and pull, but usually it's within a healthy balance.

>What did give me pause was how he handled negotiations over a clause in our potential agreement. He didn't listen to my concerns, and didn't budge one inch.

I've learned to listen to my gut in these situations. The worse your gut feeling is about an agreement, the harder you should push back on it until you can negotiate something that you're comfortable with. I usually give new relationships the benefit of the doubt once. Your first bad gut feeling can be wrong, but I've always regretted moving past a second bad gut feeling.

Be extremely suspicious if your counterpart tries to rush you through a contract negotiation process by downplaying the importance of the agreement while simultaneously refusing to budge on it.

>The amount of repos ( private ) I've stumble upon where only some documentation exists on how to build it but not even a word on what it is, what it does and where does it fit is quite high.

When you find something consistently sucks about real world projects, it is a signal that these businesses and/or the markets they operate in value things differently to you. It is possible they were all wrong in a very consistent and obvious way. Or it's possible that you are missing something.

As developers, we spend a lot of time with code and software internals. We are directly exposed to, say, the frustration of onboarding onto new projects with spotty documentation. This makes us slightly delusional about how important it is in the grand scheme of things.

Ceteris paribus, I'd bet on a business with lots of code and barely any documentation over a business with lots of documentation and barely any code.

The idea isn't "put no effort into keeping documentation up to date." It's to acknowledge that, in the real world, documentation does go out of date despite the best efforts of project maintainers. Sticking our fingers in our ears and saying "just keep it up to date then" is simply not a real position.

Despite a huge volume of tooling and methodology around reducing bugs, bugs still exist. This is a reality. One with associated costs and mitigations that we acknowledge. Likewise, the article is suggesting we acknowledge the reality that documentation does go out of date, even when effort is being put into maintaining it. That's why the point immediately preceding "It gets outdated" is "It requires maintenance" ;)

Which specific points in the post did you disagree with? "Just keep the documentation up-to-date" sounds about as practical as saying "just don't write bugs."

The impact and importance of documentation varies from project to project, but it is hard to see these hard-line takes on the importance of documentation as anything more than grandstanding. In the real world, where consumers and businesses exchange money for goods and services, and where organizations, individuals and teams must wrestle with market conditions, deadlines, KPIs and so on, documentation is a supporting act.

This doesn't say what you think it does. IBS being co-morbid with anxiety is not evidence that people are spuriously identifying as sufferers. It's the expected finding for a disorder in which psychological stress and the brain-gut axis are thought to be major causative factors.

I don't understand the mindset behind a comment like this. Where does the confidence behind this opinion come from, when the knowledge basis falls below "bothered to Google it"?

The idea of a hypochondriac making a spurious claim to IBS is pretty ludicrous. You know if you have the symptoms or not, and IBS is probably the best possible outcome for someone with chronic bowel symptoms.

Lumping PCOS in with gluten allergy is giving "shit men believe about women's health." Maybe try listening to some women before forming opinions on their reproductive health.

Classic HN conversation here.

"The web is too complex! All these web frameworks are too complicated!"

"Okay, what do you suggest instead?"

"I'd just use [completely unmaintainable technology from the 90s that is no longer supported by its vendor]"

"Okay, how would you approach [basic feature of the web framework]?"

"Stop moving the goalposts!"

Come on, you could at least come up with some hand-waving about cache headers and CDNs.

Maintaining VBScript sucked 100x worse than TypeScript.

How would you approach SSG with Classic ASP?

F5ing to refresh is a heavier workflow than the hot-reload/refresh you get with every modern web framework.

> Are there a lot of server side template languages that can’t do this?

Did I say there weren't a lot of template languages that can do this?

A dead give-away that this subject isn't as "straight-forward" as you think is that, at one sentence in, you've already misidentified the conversation taking place. This isn't about can vs can't, but about the right tool for the job.

What template language would you personally recommend for this project?

To me, that is a separate level of decision. Sure, you could avoid the whole problem of building a docs generator by using an off-the-shelf docs generator, and letting the Redoc and Swagger dev teams deal with all the development complexity.

But if you are going to build your own docs generator, React and Next with RSC aren't a bad choice. Web development just isn't as simplistic as people on HN seem to think it is.

Going by the response headers, it seems that most if not all of the HTML served by docs.mux.com consists of cacheable static files. As the OP article mentions, using React for static generation is one of the big use cases for RSC and Next.

Which templating technology would you recommend for the use case instead? Keep in mind that generating HTML from OpenAPI specs can become complex and will require plenty of maps, filters, recursion and indexing into the data in the course of transforming it into HTML.

How much experience do you have with RSC and Next.js?

I remember writing PHP and JSF back in the 90s and 00s, and the experience of both writing RSC and Next.js as well as using websites built with these technologies is simply not comparable.

I haven't used Blazor, but I shudder at the thought of using Jinja to generate the HTML here. Rendering documents from OpenAPI spec benefits from being able to easily transform data, map, filter and so on - especially if you are displaying the JSON schema for request and response bodies (which docs.mux.com appears to be doing).

The experience of doing these transformations in template languages is pretty sub par.

I agree re: scroll hijacking and with a preference for minimal styling, while noting that the styling on docs.mux.com is pretty minimal compared to other docs sites.

What I'm wondering is what the anti-React folks are recommending for generating HTML and/or DOM itself in the docs use case, since most of it needs to be dynamically generated from OpenAPI definitions.

It seems most of the content is dynamically rendered (at build time with SSG). What alternative did you have in mind?

Standard playbook in this situation is everyone involved saves face by blaming the team who were driven out, then they adjust to the new normal and everyone forgets they were ever able to build and ship software.

You could flip the order and do a sequential read from the source with a random write to the destination. It sounds like this would still suffer from poor performance on the data mentioned in the article, but it is hard to feel like some kind of opportunity hasn't been missed with index permutation.

For example, using the permuted the index mod M rather than random draw in the first pass could avoid the whole issue of oversized piles and the extra wasted space per pile.

The permutation function is essentially a block cipher on the index. It's stateless and there is no need for intermediate files or buffers. The cost of running the function should be comparable to RNG.

I did not see it mentioned in the article, but I wonder why or if the team rejected a permutation function on the index. The shuffled dataset would then be Xs[i] = X[f(i)]

I read the dishonest employee story and, candidly, I did not find it to be an example of good leadership.

You are recounting an argument that you are proud to have won, and where you are proud to have put a subordinate in his place. In your eyes, this is an example of good leadership because you did it in a way that was merely firm rather than, say, abusive.

You achieved behavioral compliance, which is definitely better than nothing, but genuinely good leadership in that situation would have involved more two-way communication, empathy and active listening to build a mutual understanding.

By the end of the article, I'm left with no understanding of what Jerry's motives were or why he behaved and communicated the way he did. You didn't seem to be interested in engaging him more deeply to find out. Instead, you seem exclusively focused on achieving your "I'm right, you're wrong" moment.

At points, you offer uncharitable speculation:

> Maybe he was feeling lazy or maybe he was trying to defend the code he'd written in the past.

Which to me raise more questions. Why is he feeling lazy? Why is he feeling defensive? These are certainly not things that people regularly experience in workplaces where they feel respected.

I did not feel your attitude in the situation, or recounting of it, was respectful to Jerry at all. At best, this interaction feels like a behavioral "quick fix" that falls short of identifying and fixing the underlying issues and risks long term resentment and disengagement.

That's not a principle. That's just a random thing that people thought back in the 80s and 90s because of some clever little comment in a spec, that sounded correct at the time but proved absolutely ruinous in the decades since.

Systems that are liberal in what they accept are paradoxically harder to develop against, undermine standards and encourage incorrect, fragile implementations. Query parameters are a classic. In practice, unrecognized query parameters almost always represent a bug in the client. Better to find out immediately with a 400.

I would extend this to unused query parameters and trailing slashes or lack thereof.

This take is infinitely more naive. Everyone knows that companies act in economic self-interest. That's not the point of contention or where the discussion is situated at all. Orosz is knowingly evoking social and moral frameworks, rather than self-oriented economic ones, for evaluating these actions.

It might aid your understanding to consider that while companies behave out of economic self-interest, socially conscious human beings have their own vested interest in highlighting behavior that falls short of social standards. Companies like HashiCorp generate brand capital by co-opting the language of human values and social cooperation. It is not unexpected that people would try to hold them accountable to their own positioning on values.

Maybe I've only worked in ass-backwards companies but it seems to me that for almost all stakeholders, including project managers, bosses and clients, the "requirement" abstraction really does mean:

> [This feature is] something that absolutely must be in the next release of the product

All this thinking is well and good for figuring out the implementation side of that abstraction. But all this thinking won't get you off the hook when you "fail to deliver." At the end of the day, the meaning of "fail", "deliver" and "requirements" is usually not up to you.

IMO the XY problem problem eclipsed the XY problem in significance a while ago. Q&A communities are full of useless XYsplaining that pollutes search results with non-answers.

If you know the answer to someone's question, and you want to be helpful and informative, then simply answer it. Follow your answer with "why do you need this btw? there might be a better approach" when appropriate. This is Example 1 from the OP. It's great!

If you can't answer a question then the most helpful thing to do is usually to stay silent. This is where the XY problem problem strikes: know-it-alls who need to have an answer for every question, who have nothing to say but still need to be heard.

I have a similar struggle and find you are largely limited to learning piecemeal. I have found the best learning resources are the technical docs, specifications, proposals and source code of major language projects and VMs. Research languages and associated research papers. Conference talks by compiler authors (Rust has some good ones).

Generated lexers are still worth it but handwritten RD won on the parsing front. No other historical debate gets this Weekend at Bernie's treatment the way parser generators do. Is it from dated undergrad + research material? There must be a reason all the references and approaches in this article are decades old and parser combinators get a single dismissive footnote. Pretty sure that Guy Steele quote even predates PEGs.

Bison and YACC are a mess. Sure, go and complicate your build by introducing code gen steps and ancient spaghetti DSLs with terrible tooling and an extra learning curve. Anything to avoid writing a readable parser in the same language as the rest of your compiler. The amount of ink spilled over parsing and parser generators is phenomenal when you consider how trivial parsing is compared to the other compilation phases. Look at source code for large compilers and you'll find the handwritten parser is some of the easiest code to understand in the project. Lack of left recursion is a trivial limitation in practice.

IME this dividing line exists more in theory than practice. Maybe your partner feeling upset or rejected leads to a fight about something unrelated the next day. Or maybe it's easier to rebuff some nagging than to deal with an insecure partner who is good with boundaries but will still feel deeply bad about the rejection.

So-called "duty sex" has been recognized as a complex topic where consent is concerned. Surely this is a continuum rather than yes/no. I can't go around calling an ex-girlfriend a rapist because she nagged me for sex now and then.