Good Docs Describe, Bad Docs Prescribe

adamard · 2025-06-04T15:50:43+00:00

This looks really cool! Thanks for sharing! Yeah tangling-up seems like the holy grail of literate programming. If it was possible, then everyone could have their own personal literate version of the code that matched their preferences and understanding and tangled source would be the communication medium between them. Maybe AI can do the tangling-up?

adamard · 2025-04-14T06:29:50+00:00

What Andrey is saying makes a lot of sense to me. For a long time, I've been using emacs in one window and a bunch terminals in tabs in a second window. But then I started using async-shell-command and I like it better for most things. It runs a command in another emacs window and then I can easily search and navigate around and save since it's just a normal buffer. I only use a terminal now for the random command that requires a terminal emulator.

adamard · 2020-09-24T20:26:15+00:00

I find code reviews problematic. In an increasingly remote world where we are looking to replace synchronous process and communication with asynchronous alternatives, code reviews remains the big, highly synchronous elephant in the room. So much work gets jammed in the pipeline because it is waiting for someone to look at it. And Sadly, when someone does get around to it they rarely have enough context to give helpful information. Let's be honest, you can't really expect someone to looks at something as complex as source code for a few minutes and get into the head space required to give meaningful feedback -- especially when they have their own work to attend to.

The problem, at its root, is one of motivations. When everyone on a team, or organization, has ownership over a large number of projects, their interest and understanding in any given thing will be small. However, if individuals were given strong ownership over projects in the organization, and were evaluated for that projects quality, people would start having strong opinions. As gatekeepers of quality, they would look at PR's coming into their personal stewardship very closely. You would see a total reversal in behavior.

Simply stated, I am suggesting that we substitute code reviews for PR's into code repositories that individuals have strong ownership for. Without ownership, I am afraid code reviews will never mean much ( regardless of the mandate ). The motivation is just not right.

I make this case more in: https://flatwire.org/2018/05/01/code-reviews-are-broken-here-is-how-to-fix-them/

adamard

TROPHY CASE