document target features, runtime detection, and multiversioning

[enthropy7]

Hi! I'm a computer-vision engineer who's worked with SIMD daily for a few years. This is the first PR in a series aimed at #29, making SIMD docs cleaner for beginners ( following the contributing guidelines, I'm splitting one large doc update into smaller, reviewable pieces )

This PR fills in the "How to get the most out of Rust SIMD code" block:

• feature levels, including is_x86_feature_detected!
• #[target_feature]
• #[cfg(target_feature)]
• how to do "multiversioning"
• multiversioning, why or why not?
• when do you use std::arch instead?

It also clarifies the existing "automatic UB" section: the UB is about
executing an unsupported instruction, which is exactly what makes
per-function #[target_feature] + runtime dispatch sound.

[programmerjake]

other than that, looks good

View changes since this review

[workingjubilee]

My apologies, @enthropy7, but I cannot accept this documentation PR. While it may be technically adequate in the checkbox-filling regard, I and my colleagues share concerns about the source of the text. I do not wish to waste your time, so I will not beat around the bush. We think it uses LLM-generated output.

We have suffered significant backlash for even once publishing something based on LLM output. "I extensively edited it" or "I just had it clean things up a bit" does not cut it. That still counts for the purpose we are concerned about, and the loss of trust we risk is too severe¹.

Even if it does not use LLM output, then it seems particularly "listicle" in style in a way that we do not wish to be in user-facing documentation. It's a bit of a "Caesar's wife"² situation, you understand? I don't particularly like it, but it's where we are at.

If we worked on this text in review, we might be able to improve it to the point we could merge it. However, I think that is a poor use of reviewer time, which I find difficult to allocate anyways. It would also risk a more disrespectful process that you would be ill-inclined to endure, especially to the degree that it isn't LLM-generated to begin with.

Such review would not address the public relations question that motivates this response. Normally this is where we would invite you to talk about this on our Zulip and maybe discuss alternative approaches. However, trust and familiarity is important to being able to author something we can land in this regard. Blocking a PR until we trust you extensively would lead to a ridiculous delay. So, I would only suggest any followup if you want to do something entirely different than submitting non-trivial documentation PRs for... a while.

Footnotes

1. https://writethatblog.substack.com/p/dev-reaction-to-ai-blog-posts ↩

2. https://en.wiktionary.org/wiki/Caesar%27s_wife_must_be_above_suspicion ↩

[enthropy7]

Hello there. Can you explain me, why my PRs was closed with LLM gen tag? Even if you can open my ghub and see fork of portable SIMD's where branches were created when i started working on them, and the text is based on Docs of Rust std::/Arch's and tried to explain things that person who NEVER worked with SIMD's could understand what is this and why he need/doesn't need this. What kind of reputation I should get, that my PR could be merged? i should create themes here even for small PR's like closing issue that's in the project for almost 5 years and takes nothing than time to solve it? i could rewrite it not in that why/why not style, but it's thing that docs should avoid as fire from my POV. the main point - author can provide information that are valid only from subjective point, but when you provide different takes OR explanation why - reader can form his own opinion. i can understand that structure of docs looks too polished and LLM was used to draft the text, I edited and directed it, rewrote it, but saved the structure, cause it's human-readable, as i talked before. i saw that "i used it a bit" is a no excuse, but i'm honest with you. i'm excited to do all that in my powers to get PSIMD stable and i opened that PR cause i want to contribute to project, what i wish will crave out of nightly someday. i use rust + CV everyday at my work and experimenting with optimization etc, thus SIMD is part of my life and i really want to get rid of boilerplate SIMD code by using this crate when it become stable. Docs seems to nice point that should be closed first, because after my point of interest was blocking issues that was mentioned few times. I was scanning for issues that was opened way before recent ones. that's only reason. Also i would like to mention that i'm looking forward to work on real problems, that need discussion or hard work. And i can understand your rejection - i'm not a contributor of PSIMD project, thus that PR looks like random one or spam, that was created to farm merge in profile, but in that message i'm clarifying - it's not.

If docs not a priority before fixing main issues, please, point me to something that i can work on.

P.S: As non eng-native person, there’s literally no existing normal ways to get text edited properly without using LLM, that’s why you see the difference in building sentences in that message, that i specially wrote by my own hand completely, and normal text that’s ready to publish almost everywhere.

[jyn514]

i can understand that structure of docs looks too polished and LLM was used to draft the text, I edited and directed it, rewrote it, but saved the structure [...]

P.S: As non eng-native person, there’s literally no existing normal ways to get text edited properly without using LLM, that’s why you see the difference in building sentences in that message, that i specially wrote by my own hand completely, and normal text that’s ready to publish almost everywhere.

@enthropy7 i understand that you spent a lot of time and effort on this PR, and i'm sorry that that's wasted. i want to say that it is much easier to take non-native English and turn it into something we're happy to publish than it is to take LLM-generated English and turn it into something we're happy to publish. if you write this in your own words, possibly using an LLM for review to spot grammar issues and typos, but not to draft the prose, we are much more willing to accept your changes.

we are not going to accept LLM-drafted docs for the reasons Jubilee's stated above.

[enthropy7]

i can understand that structure of docs looks too polished and LLM was used to draft the text, I edited and directed it, rewrote it, but saved the structure [...]

P.S: As non eng-native person, there’s literally no existing normal ways to get text edited properly without using LLM, that’s why you see the difference in building sentences in that message, that i specially wrote by my own hand completely, and normal text that’s ready to publish almost everywhere.

@enthropy7 i understand that you spent a lot of time and effort on this PR, and i'm sorry that that's wasted. i want to say that it is much easier to take non-native English and turn it into something we're happy to publish than it is to take LLM-generated English and turn it into something we're happy to publish. if you write this in your own words, possibly using an LLM for review to spot grammar issues and typos, but not to draft the prose, we are much more willing to accept your changes.

we are not going to accept LLM-drafted docs for the reasons Jubilee's stated above.

thanks for your answer, appreciate it. to clarify, in my sentence -> drafting means taking some hand written words by your own hand that looks like unstructured thoughts -> put this into LLM -> take the normalized output -> continue editing text and finalizing that product. not just inserting prompt. LLM's even doesn't now about most of things that were listed in my PR's. (as a tech writer) i saw that as a normal process, that doesn't lead to slopification of material or docs. and i'm still open to closing that gap in docs or any other fundamental basics, just to bring PSIMD closer to stabilizing.

[jyn514]

that makes sense to me :) unfortunately LLMs have a very distinct "style" that is hard to avoid. that style is much easier to detect for native speakers than for ESL speakers, which is why we have a much simpler rule of "don't have an LLM write docs at all", to avoid situations exactly like this where the docs look fine to you but not to us.

[RalfJung]

As non eng-native person, there’s literally no existing normal ways to get text edited properly without using LLM

As a non-native speaker who spent a lot of time learning how to do good English technical writing, I have to disagree strongly with this claim. It's a skill one can learn, just like coding. (It's harder than coding, at least for me.) It may be tempting to use LLMs as a shortcut to skip learning that skill, and depending on your levels of English proficiency it may even be hard to tell apart good technical writing from LLM-generated writing, but there's still a meaningful difference that is felt at least by many of our users.

Also FWIW, many native speakers are not great at technical writing either. So it's not really about native vs non-native. I understand you want to help, and it can be frustrating if the resources to learn the skills needed to help effectively are not easily available to you. But I am afraid an LLM is just not a good substitute for such a task.

[enthropy7]

As a non-native speaker who spent a lot of time learning how to do good English technical writing, I have to disagree strongly with this claim

obviously, I don't mean to say that you shouldn't learn the language, and you are completely right. I'm just trying to say that if I spend two years polishing my English to a C1 level, becoming capable of doing fully hand-written work, practicing a lot, and regaining my fluency and grammar, I must also change the way I build sentences, because it is not correct to write like that in documentation. as a result, the documentation would be finished eight years after the issue was created, not six.

[workingjubilee]

My employment before I took up programming was in editing translated works. Translation rarely makes a perfect example of the "target" language, and benefits significantly from that kind of editorial labor. Based on my experience, I can assure you that LLMs are not required for editing somewhat-garbled English.

Normalization of output is not the primary goal of editing and even if it was, I am not convinced that is what LLMs do. When we talk about things like compilers normalizing code, they strip away things that are not necessarily relevant to conveying the meaning in the target language. However, LLMs tend to reduce the original meaning in the words they touch. https://arxiv.org/pdf/2603.18161

...They also seem to eagerly add irrelevant fluff, which is neither of those things.

[enthropy7]

However, LLMs tend to reduce the original meaning in the words they touch. https://arxiv.org/pdf/2603.18161

agreed, but as i mentioned before, that's a tech doc. it shouldn't carry my own opinion through the text or present a one-sided view on some topic, thus it must be neutral, but still contain enough material. most of the problems that LLMs bring to things outside tech don't concern us here (i'm talking about misrepresentation of author's thoughts etc.). the reasonable problem here is sloppy bs code/text trying to sneak into big repos, but not in our case. i still don't see any problem with editing those docs to a mergeable state in a small amount of time. after that PR, many people with great knowledge of English reached out to me and offered some help, tho, they could just rewrite my words with my guidance into something everyone would like

[workingjubilee]

Technical writing that has reduced meaning is not merely more neutral. It is less informative.

[enthropy7]

personally, i don't see what information is still missing from any of the 3 PRs. if we talk about this one, the Multiversioning part is the deepest one, based purely on my own experience, not just knowledge. i spent a lot of time on that topic. and from my point of view that's the weakest point, cause you need some prerequisites to understand what is it and why is it exist. i rewrote it 3 or maybe 4 times. since this is a beginner's guide - i or someone else mustn't overload it with things that someone might not understand and would just skip.

[workingjubilee]

Then it seems you have already noticed that it should be leaner than my original idea, which was an... incomplete thought, I think.

That is also why I "simply" rejected #536.

I am happy to discuss what I was thinking at the time and the difference to now. It would probably result in a slightly different direction than just redoing this PR over again. Even if it did wind up with you just submitting the original pre-LLM text for this and us reviewing that with some editing, I think it would be more productive to start the conversation over again, maybe via Zulip or on the issue or something, rather than simply resuming in this PR.

[enthropy7]

sounds good! let's continue tomorrow (it's a late night in my timezone) and get the docs into the right shape

[workingjubilee]

If I find a spare erg, I may write down some of my thoughts on a more concise/minimalist/"at the very least, first things first" approach on the issue.