It's only a 5-year high. Do they not have data before 2020? I need data over a much longer timeframe than 5 years to determine how interesting the 27% number is.
Lots of people have tried it. The problem is the sheer number of rules in a typical technical writing style guide. I continue to believe that a fine-tuned model is the way to go, and I made a lot of progress on that front, but I learned firsthand how labor-intensive feature engineering can be.
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.
I had moderate success using https://www.iso.org/ISO-house-style.html converted to markdown and narrowed to the guidelines starting with "Plain English" and ending before "Conformity and conformity-related terms" (plus a few other rules up to and including "Dates"). A quick estimate puts the whole Markdown document at 9869 tokens - quite manageable. I generally prefer the style of the Microsoft Writing Style Guide but ISO house style is the only one that fits nicely into a prompt.
One agent and some hard code to extract doc diffs with relevant code, parallel agents for different rule groups, tool agent to look up existing patterns and related material in the codebase, consolidator agent to merge the comments and suggestions, that’s how I would do it, for the first version at least. All of them fine tuned, ideally.
Looks solid. My gripe with most technical writing (TW) style guides (this one included) is that they mix best practices with conventions:
* "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.
I’ve been on both sides of this, and I’ve come to the realization that it depends on the audience of the writing. It seems like this is for Red Hat authors writing miscellaneous docs for a range of users. Consistency is important there, so that Red Hat seem consistent in their messaging, as a single user could be reading material from many authors. It would look sloppy if the small stuff is all over the place.
Many times, a user receives communication from a single writer. This could be a consulting arrangement, or a small company, or any number of cases really. Those users are probably going to be consistent with themselves anyway, so there’s less need to be as specific on the small stuff. In that case a guide is really just trying to knock off the obvious rough edges in someone’s writing to make sure they’re actually communicating the information.
Using a monospaced typeface for that purpose isn't only convention; it reflects the fact that when those commands are typed literally, it will be in a terminal which almost certainly itself uses a monospaced typeface. I think I'd say that setting literal command text in a monospaced face is a best practice.
[EDITED to add:] I agree with the general point about distinguishing best practices from conventions, though. (But there are also intermediate possibilities. "Best practice for us because it fits with conventions we've become used to". "Best practice for us because of some peculiarity of us or our work, even though for other groups it might not be so good".)
The convention is used also for strings entered in a proportional font such as an address bar. I think the primary reason for the convention is most fonts where all characters are distinct are monospaced. But terminals being monospaced typically contributed surely.
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.
If it turns into treating it as a “should” then my experience is yes, definitely, that’s a death knell for basically anything. Without the “should” it continues to be fun. The trick is threading that needle.
It is said that God wrote the entire language for to use in a book and that we shall model ourselves off of it. Once it was done, God turns his back on the book and Satan sneaked in and added two words - "Should" and "Aught".
Tangentially related, I published some notes about "docs for agents" (e.g. `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, etc.) yesterday
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"
Has anyone found significant-enough differences to not just make one overarching LLM_GUIDANCE.md and symlink it to the others there?
This also strikes me as such an organic (ironically) problem that it probably makes sense for everyone to pool their prompts together, together with their observations, to try to discern what patterns tend to work.
This is my honest assessment of the calculus of the move. Please don't interpret any of this as me personally supporting or approving of these motives. I'm just trying to have a genuine intellectual discussion about the potential thought processes of our collective leaders.
* 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?"
So there's no AR aspect to the lens on any of these Meta-partnered smart sunglasses, right? I assumed that was standard on all of them. Naive, I know, because that would require some amazing hardware. But it does go to show that we're still far from the Star Trek future that other simpleton consumers like myself might be hoping for / expecting.
There is no screen at all on these - there are some other glasses in the market that have some visual aspect (not environment-aware but spatially aware enough to keep a virtual monitor in place). This one is the current market leader I believe: https://us.shop.xreal.com/products/xreal-one-pro?srsltid=Afm...
