13,539 karma · joined May 10, 2016
> When the workshop returned the wooden balls, he tested building some molecules. This was when he had a moment of insight: there was a vast amount of information baked into the holes’ positioning. The model molecules automatically had the correct form and structure, because of where the holes were situated. This insight led to his next idea: what would happen if he utilised the atoms’ inherent properties to link together different types of molecules, rather than individual atoms? Could he design new types of molecular constructions?
Are there any libraries similar to Doxylink [2] that ensure that links from Sphinx to pdoc (and vice versa) are valid?
[1] https://news.ycombinator.com/item?id=25903595
[2] https://sphinxcontrib-doxylink.readthedocs.io/en/stable/
> August’s job report also included a downward revision to June, which showed the US economy lost 13,000 jobs that month. It’s the first negative employment month since December 2020, and it brings to an end what was the second-longest period of employment expansion on record.
(Quoting from that post)
Arguments in favor of keeping them separated:
* Writing style. In agent docs, using all caps might be an effective way to emphasize a particular instruction. In internal eng docs, this might come off rude or distracting.
* Conciseness vs. completeness. In agent docs, you likely need to keep the content highly curated. If you put in too much content, you’ll blast through your API quotas quickly and will probably reduce LLM output quality. In internal eng docs, we ideally aim for 100% completeness. I.e. every important design decision, API reference, workflow, etc. is documented somewhere.
* Differing knowledge needs. The information that LLMs need help with is not the same as the information that human engineers need help with. For example, Gemini 2.5 Pro has pretty good built-in awareness of Pigweed’s C++ Style Guide. I tested that assertion by invoking the Gemini API and instructing it Recite the Pigweed C++ Guide in its entirety. It did not recite in full, but it gave a detailed summary of all the points. So the Gemini 2.5 Pro API was either trained on the style guide, or it’s able to retrieve the style guide when needed. Therefore, it’s not necessary to include the full style guide as AGENTS.md context. (Credit to Keir Mierle for this idea.)
Arguments against:
* Duplication. Conceptually, agent docs are a subset of internal eng docs. The underlying goal is the same. You’re documenting workflows and knowledge that’s important to the team. But now you need to maintain that same information in two different doc sets.
Quite badly. Can't tell you how many times an LLM has suggested WORKSPACE solutions to my Bazel problems, even when I explicitly tell them that I'm using Bzlmod.
I technically have an A.S. in C.S. from that community college, but I think my circuitous path fits the "non-traditional STEM background" criteria.
Computers have been great to me! Very thankful that I stumbled into this path.
The most reliable non-fine-tuned method I have seen is to do many, many passes over the doc, instructing the LLM to focus on only one rule during each pass.
Almost everything in there falls under the "best practices" bucket and there is little discussion of "conventions". If I did it again today, I would try to provide lots more justification and evidence for each guideline.
The upside is that authors focus their limited time/energy on the edits with the highest ROI. E.g. if the author only has time to either A) make the content more scannable or B) use Oxford commas everywhere, I would much prefer that they spend their cycles on A. This doc also reduced friction at review time. When some proposed new content didn't meet my quality bar for whatever reason, I would point the author to specific sections of this doc and ask them to revise their draft based on these guidelines.
During a code review, a request to fix a race condition is much higher priority than a name improvement. I'm arguing that TW style guides need a similar type of distinction.
I can pick out specific examples of best practices versus conventions in the Red Hat guide if it's still not clear.
* "Best practices": Aspects that tangibly improve docs quality. Usually backed up by experimental data or overwhelming consensus.
* "Conventions": Arbitrary decisions that don't clearly improve docs quality one way or the other, except for the fact that they improve consistency, and consistent docs are easier to use.
When everyone in the room has this shared understanding, TW style guide conversations often go much faster and smoother.
It's more focused on implications for docs strategy (I'm worried that agent providers are steering us towards duplicating information that's already in eng docs) rather than user best practices i.e. "put this into your agent doc to improve agent performance"
Claude Code seems to require the CLAUDE.md filename.
* Quick, victorious wars can be incredibly popular domestically, regardless of whether surveys say that only 16% of the US population supports the war. Trump needs an approval ratings boost. The global tariff shock was a PR disaster. A quick, victorious war is a tried-and-true approval rating booster over the last 200-300 years. The key, of course, is actually keeping the war truly short and victorious. If it drags on, or if people start asking "have we truly won?", then that's a whole different matter.
* We have moved out of a unipolar geopolitical world and into a multipolar one. The USA is checking the ambitions of the rival powers. Want to invade Ukraine? Sure, go ahead and try, but it will be a multi-year slog. Want to go for years maybe developing nuclear weapons, maybe not, and making US antagonism a central part of your political platform? Watch us systematically attack your nuclear program and and air power and do highly targeted assassinations of your political elites over the course of two weeks. Want to invade Taiwan? Look at what happened in Ukraine and Iran and maybe reset your expectations about how that will pan out.
* There has been a lot of questioning lately around whether the US will actually help their allies when they're in a pinch. This is sending a pretty strong message of reassurance to allies.
* Trump may actually want things to escalate to a point where he can reasonably declare martial law within the US. How do you stay in power when you've already hit your two-term constitutional limit?
Your question was "how does it benefit the US?" but I don't think that's answerable because everyone has a different take on what's best for the US. It's much more feasible to discuss "how does it benefit Trump?" or "how does it maintain US's position as a world power?"