[mjburgess]

Perhaps you should ask the manager why he passed it through AI.

It might be that with precision, readability is lost. It's a tradeoff: the more compressed your language is, and hence the more precise, the more cognitive effort you require the reader to expend on each word. Reading is a translation from your mental model, as expressed in words, to the readers mental model. Words alone don't perform this translation, the act of reading and interpreting does so. With your concision you give no help to the reader in this process.

One suspicion I have is that your one-pager was passed through AI because it was too terse to serve the job of aiding the general reader in obtaining an understanding of the topic for themselves.

Writing to be read by an audience is a vastly different activity than writing notes that merely, precisely, document for the maximally informed highest-context reader (or one willing to do the work of reassembling this context during reading).

When you're writing for others, especially a "generic other", you're expected to adopt their uninformed, low-context, high-difficulty reading position, and fill-out the prose in an aid to their understanding.

This will involve: repetition (restatement with different words and ideas), illustration with simple examples, grounding in examples most likely to be familiar to them, explicit statement of steps/procedures/processes that breakdown topics/actions into small units which are each easy to immediately understand, possibly: some humor to break the effort of reading, some asides which engage or interest the reader, some context which makes the reading reelvant to them so they will be willing to expend the effort to read it.

[cthor]

This is an insane response to someone having their carefully written work casually bastardized by an LLM that rewrote the entire design spec without even being informed. The amount of institutional noise generated by such carelessness far exceeds whatever improvement in readability you could possibly imagine. Any criticism you could aim at the original text that you don't even have on hand (i.e. are completely speculating wrt its readability) you could direct 100x over at the manager's horrible communication skills.

[mjburgess]

You're assuming malign motivations, I'm assuming misplaced ones. It seems more likely to me the manager tried to read it and struggled, then generated something of equivalent size or larger. I'm taking it the generated document passed around was actually at least as large as the one-pager, and hence entirely pointless to rephrase even with the malign motivations you're assuming.

Since the poster here wears his personality and writing motivations on his sleeve, it is very obvious to me that he writes at cross purposes with those who read. he says very clearly: he writes for precision, expended a vast cognitive effort per word.

Even if, in this instance, my analysis is wrong -- its a comment for the poster here worth considering. Because people don't like to read writing which has taken such effort to produce, because it then requires a great effort to read.

[nicoburns]

> It seems more likely to me the manager tried to read it and struggled, then generated something of equivalent size or larger.

Either way, it's poor management to interpose oneself between employees. As a manager you should be connecting groups of people to talk to each other directly, not injecting oneself as a go between. If they have issues understanding the material they're much better off asking the OP directly than asking the manager who doesn't understand it either. And they'll be in a much better place to do that if they have read the material OP actually wrote.

[godelski]

  > it's poor management to interpose oneself between employees.

I didn't interpret mjburgess as defending the manager or even condoning the action. In fact, I read their comments as recognizing that action as a failure.

The difference is that mj was trying to give advice to donatj, and donatj can't control what their manager does. So the advice is crafted such that it gives actionable suggestions to donatj.

Yet, that might not be the correct interpretation. I don't know, I'm some third party, like you. Personally I agree that this is poor management but I don't think just blaming the problem on the manager solves anything, it just leaves the problem broken. So the things to do are either fix the problem or figure out how to work with the broken thing.

[watwut]

> So the things to do are either fix the problem or figure out how to work with the broken thing.

So, I will say that if you did not seen or read a text in question, there is no way for you to accurately diagnose issues with the text and give out advice on how to make it better. Such advice from someone who simply assumes the way the text was wrong based on some manager rewriting it with ai is less then useless.

It is, frankly, ridiculous to think one can give meaningful advice about text you have never seen. And then double down in comments.

[sokka_h2otribe]

It's not based on writing they didn't read...

The feedback is to the author of the post complaining (understandably) about their manager using AI and destroying the carefully written document.

That post alone is plenty to give feedback on absolutism and the nuances of existing in the world with mostly neurotypical people. [My interpretation of the feedback]

We dont care about the manager, they don't matter. This is not "defending" or "justifying" the manager, in case you see it that way.

[godelski]

  > It is, frankly, ridiculous to think one can give meaningful advice about text you have never seen. And then double down in comments.

I'm not the manager, there's no doubling down.

As for answering the question, you're right and wrong. You're right that I don't have enough information to give specific and nuanced suggestions. Like you said, I didn't see the original doc nor the AI rewritten one. I only have OP's comment. But you're wrong because I do have enough information to write the advice that I did. The advice is still broad because that's all that I can give with the information I have, but that doesn't mean it is useless.

You accuse me of not reading, but I'd encourage you to read my comment again. I explicitly stated that I am not advocating for what the manager did. I explicitly stated that I think it was wrong to do. But we're trying to solve problems, right? I took OP's comment as a legitimate request for help. Maybe they were just complaining and wanted someone to validate them. But hey, they posted in public and so are going to get a wide range of interpretations. That can be helpful, but may not be what was intended.

So either we try to respond to each other in good faith, acting as if everyone here is not acting maliciously, and trying to do their best, or we fight. I'm sorry, but that's what the situation is. If you just want to poke problems with things, then you're not helping. There are issues and limitations, and you're more than welcome to point them out but don't treat the setting like we're enemies. We're not. If you can't figure out how to critique while being collaborative then you aren't going to work well with others. And who knows how effective what I've said is. All I have to respond is your one comment that feels out of place to me. IDK if it's an off day for you, you didn't read right, I wrote wrong, or one of a million other things. But I'm trying to work with others (including you), are you trying to work with us?

[mjburgess]

Well, OP can learn from the experience or turn it into a hill to die on. Learning doesn't imply you were ever wrong, only that something you did produced an unintended result -- people are themselves problems to navigate around, not people whose actions you have to read as judgements.

[idiotsecant]

The op is probably not the world's most reliable narrator. Based on his very, very specific preferences around writing I'm guessing he can be a bit prickly when it comes to feedback. The manager might have had a bad day and dreaded having the conversation and ended up with this. Still very stupid, but OP is not quite so clearly the martyred hero in this version.

[IAmBroom]

Agreed. Anyone who believes they can write an English sentence that is clear, exact, and bulletproof is foolish at best.

This is the reason professional jargon exists: to narrowly define certain words. But even then, only a tiny fraction of words are so restricted.

[sjsdaiuasgdia]

When I read documentation, I'm not there to enjoy the experience. I'm there to find out how the documented thing works and how to use it. It's not a novel. I'm not there for entertainment.

Chasing readability without maintaining accuracy is a failure in the context of documentation no matter the motivations involved.

I'm not saying that readability can't be a consideration when making documentation. I am saying that if you discard accuracy in the process, you've fucked up quite badly.

This anecdote would likely be very different if the AI-modified version had been passed back to engineering for a review before sending it out.

[crispyambulance]

> I'm not saying that readability can't be a consideration when making documentation. I am saying that if you discard accuracy in the process, you've fucked up quite badly.

You're right to elevate accuracy to a high level of importance, but that is NOT ENOUGH if the thing is has poor readability. The audience has to be able to understand the document if the document is to be useable.

There's only a certain amount of effort anyone can deliver in producing a document. But if the author can't deliver readability, they need to follow up the document with a lot of support and/or get some help to make it useable.

[sjsdaiuasgdia]

I've struggled through some absolutely awful documentation over the years. I'll put up with incredibly broken English and other problems as long as the accuracy is there. Just last week I encountered a pinout diagram that used emojis to indicate which pins related to which data channel. Not a choice I would have made, and I found it made the diagram harder to read. But it was accurate - I wired it up per the diagram and everything worked as intended.

Documentation lacking accuracy is useless. It can be the most readable thing ever produced, but if it describes a different thing than what was intended to be documented, it's trash. Documentation that is hard to read but is accurate still has value.

Regarding "follow up the document with a lot of support" - did you catch the part of the anecdote where the author is having to deal with support requests because of the inaccuracies?

[pwdisswordfishq]

> You're assuming malign motivations, I'm assuming misplaced ones.

Sufficiently advanced incompetence is indistinguishable from malice.

[butlike]

And sufficiently advanced technology is indistinguishable from magic.

I'm not seeing the point.

[MichaelZuo]

Bingo, it’s pointless trying to suss out beyond a certain threshold.

Just assume it’s a mix.

[moffers]

Or, to put another way, “never attribute to malice what can be explained by ignorance”

[lamasery]

I would assume the manager's a terrible reader and writer.

Most people are. Most managers are.

It's one of those upsetting things I've learned about the world as an adult, that's sharply contrary to what I believed as a child. I kept being surprised by all kinds of things until I began really to appreciate that, simply, most folks aren't especially literate. Even ones who attend and attain degrees from universities—surely at least nearly-all of those people can read and understand "college level" texts with some fluency? But no, that's, somehow, not even close to true.

[nh23423fefe]

> Because people don't like to read writing which has taken such effort to produce, because it then requires a great effort to read.

I disagree, but stipulate that. Why would this be reasonable behavior when doing knowledge work?

[klustregrif]

> It seems more likely to me the manager tried to read it and struggled

Well obviously the manager struggled to read and understand it and also struggled to read the AI results. The clear root cause is utter incompetence on the managers part. Any feedback they wanted to give could be given, but you NEVER pass along modified documents as though they where what another author had created AI or not. If you don’t like it you can provide feedback or ask to coauthor another document, you never just append TFTFY with changes and send it along with the original author standing to take the consequences of whatever you cooked up. It’s just complete incompetence on the part of the manager.

[watwut]

> You're assuming malign motivations, I'm assuming misplaced ones.

And in the process, you give zero benefit of the doubt to OP. You just assume he wrote it badly.

[3form]

I see this behavior in many people, usually conflict averse. In a poor attempt to mediate, spread incompetence like butter on a slice of bread. Ranges from tiring to infuriating.

[butlike]

If you remove AI from the conversation, it still sounds like he needs an editor.

[MollyRealized]

It is not insane, but we are talking at cross-purposes here. It is not insane to tell someone to write for their audience.

[plumbees]

I thought the reply was generally helpful. Something to consider about in my equally exacting wording as I share the same frustration as the original comment and this give me a framework to view possible issues with my own writing. I.E. You can't change what others will do, you can only change what you yourself do. In this case: Carefully crafted exacting documentation is being ignored = frustrating to me = can't change if others don't want to read it =;;; sorry I have a more elegant way to do this: My meaning is thus: While it is sometimes easier and apt to blame others for their actions, blaming others doesn't actually contribute to any meaningful growth or change. If you take on the blame yourself, even if 100% of the blame falls on the somebody else, then it leads to open ended questions on how that process can be better. Given that you have no control over other people, blaming yourself shifts the issue back onto you for a solution. This can reveal a treasure trove of oppurtunities not before explored. It can be as simple as understanding that there are different levels of technical documentation: How-tos, vs explanitory, vs laymen, etc. Or it could lead to a different exploration as to: How did I end up in this situation, what is the mistake that *I* made? Which could be an easy fix or it can be a philosophical or temporal fix. I made the mistake of:

+ Assuming people cared about this as much as I do

+ Allow another person to control then narrative: (I could have sent it out to stake holders myself; and bare whatever consequences from my hiearchy)

+ Not written any documentation and given the endpoints to an AI to communicate to laymens (because I may or may not have communication skills)

+ Take a course in communication The list goes on and on, but the beauty is that sometimes it's truely and deeply philosophical such as, because I trusted somebody who wasn't to be trusted; because I'm in the wrong place and *know* I know I should be here.

Shifting the blame to the self is less about accepting blame and more about introspection and it is the most valuable lesson I learned from my wife when we first started dating. (It help me identify that as a person I tend to blame others first before blaming myself, and to spend 10 years practicing the muscle to reverse that order)

TLDR: You have willpower, use it by taking ownership over yourself. This is a learned skill and is not enate and requires breaking preconceptions and stepping out of yourself to find.

[plumbees]

Based on other comments in the thread but not any direct reply to mine. I would also express that I was surprised when a coworker of mine complained that nobody read message boxes we put up to help the user. It was my first corporate job and I had already learned and ingrained from my experience at a small office that nobody reads technical instructions either. That alas also requires training. Usually by having the documentation open and doing exactly what is written with them watching, or with them doing (better). (Helps reveal gaps in documentation such as, Oh most users don't know how to traverse a file system, let alone what one is... how?, It's an analogy to office filings which they did everyday? why??? I never understood but, alas I've never been able to teach somebody who doesn't understand the file system, the file system.... my weakness)

[sersi]

> It might be that with precision, readability is lost

The poster you replied to just wrote a comment on HN that is meant to be read by an audience, is clear, well written and well structured. Given that, why ever would you assume that the documentation that same poster produced would be too terse to serve the job?

[rayiner]

Ding ding ding, correct answer! OP's target audience was people who are supposed to be using an API endpoint. It's self-evident OP can write clearly enough to communicate with the target audience.

[dogleash]

Your post is a masterclass in slippery middle manager yapping.

They tried to punch up a deliverable and didn't even check that their new version served the purpose of that deliverable.

If parent poster's story is even half true, I'm reminded of the phrase "reckless disregard for the truth." This is one of the vast majority of times where it's perfectly legal to be reckless with the truth, but I can't think of a more succinct description of core problem.

[Henchman21]

You just did the fucking thing he was complaining about. Holy shit I have never seen a point so well made on HN, well done @donatj

I believe the correct word choice here is "obtuse".

[david-gpu]

This is such a good summary of effective communication practices. It was the same sort of thought process that I went through when writing technical documentation and presentations, and it served me very well.

[grvdrm]

> One suspicion I have is that your one-pager was passed through AI because it was too terse to serve the job of aiding the general reader in obtaining an understanding of the topic for themselves.

One idea for you: provide a reference to an explainer with more context, examples, etc. The original one-pager might be instructions. Do A, then B, then C, without context for the purpose of not confusing the consumer with other information.

[balamatom]

>Perhaps you should ask the manager why he passed it through AI.

Note that the manager may or may not have incentive at all to provide useful or even meaningful feedback.

I mean, he did pass on an incorrect version of the documentation, didn't he?

hi! yes. perhaps he wil write inchoate sentence like point out which word is wrong

>One suspicion I have is that your one-pager was passed through AI because it was too terse to serve the job of aiding the general reader in obtaining an understanding of the topic for themselves.

"Too terse" beats "factually wrong" any day. Anyone who claims otherwise is evil.

>Writing to be read by an audience is a vastly different activity than writing notes that merely, precisely, document for the maximally informed highest-context reader (or one willing to do the work of reassembling this context during reading).

Now do "writing to be read by an unwilling audience", and "writing to be read by an audience that controls the feeder and shockprod".

[mjburgess]

On your last sentence:

The very first sentences should clear warnings not to modify the document, and read it entirely. That the contents of the document are short (<5min of reading) and extremely important. That a lot of effort has gone into making the document short, to the point, and easy to read/use.

And if that still doesnt work, arrange a 15min meeting with relevant stakeholders and go through the document quickly before releasing it.

It is my view that we have always been an oral species, and the great tyranny of the written words always a great burden, and any writing of any complexity or technical depth, out of reach for all but an elite.

Speaking to people in a meeting allows them to emote, express difficulty of understanding, understand the sentiment and priority of what they're hearing -- and most of all, it allows them to listen rather than read. People speak at a much lower information density, and this is a less taxing form of communication.

Writing has always been a great burden. It should not be elevated to, nor equivocated with, some great utility or intellectual practice. That was for an era where sound was harder to record and transmit than words; and where meetings required moving around the world.

A kind of writing which makes reading even harder is an even worse pathology. This isnt writing for a species of ape, but some one deranged enough to expend cognitive effort in such inhuman ways.

[rayiner]

> Speaking to people in a meeting allows them to emote, express difficulty of understanding, understand the sentiment and priority of what they're hearing -- and most of all, it allows them to listen rather than read. People speak at a much lower information density, and this is a less taxing form of communication.

Is that why everything is a Youtube video these days instead of written articles?

The real danger of Tik Tok and Youtube is that it allowed people who can't communicate using writing onto the Internet.

[mjburgess]

Yes, see my comment below. Memo -> meeting, book -> podcast / audiobook, newspaper article -> 10min youtube video, even, meme -> yt-short/tiktok

People are naturally motivated to watch, listen, and interact with other people. There's less a need to explain why cognitive effort is required, lower risk to bounce-off the format because it's to difficult/boring/frustrating/etc. We're already primed to expend effort interacting with others.

I think there's also something more naturally-fit to our attention spans in oral media. Whilst people frequently claim our attention spans are dropping -- I think this is false (and some research agrees). Instead, media is being adapted to fit what our attention spans always were.

It is just in reading, and engaging with long-format content, our minds frequently drifted. We frequently stoped paying attention and returned, over and over.

Instead, with shorter oral media we largely pay more attention but over shorter intervals.

A conversation also proceeds to manage attention/interest/etc. well, in somewhat dynamically adapting itself to the level of cognitive effort its participants are willing to spend.

Certainly I find myself naturally adapting my phrasing, humor, and so on according to the people i'm talking to -- based on whether they are showing interest, listening, understanding and so on. This is how attention should always have been managed.

Writing always was, in my view, a necessary evil for the vast majority of purposes to which it was put. Now, not all, of course -- we still need checklists, scripts, technical notes, accounting books, and the like.

[rayiner]

> Yes, see my comment below. Memo -> meeting, book -> podcast / audiobook, newspaper article -> 10min youtube video, even, meme -> yt-short/tiktok

Yeah, a dog can understand spoken words but can't read a memo. We should strive to use our human faculties and hold others to that standard, instead of lowering ourselves to communicating like animals.

[yyy3]

>Writing has always been a great burden. It should not be elevated to, nor equivocated with, some great utility or intellectual practice. That was for an era where sound was harder to record and transmit than words; and where meetings required moving around the world.

Okay Socrates[1]. Obviously writing has not been a "great burden" because it's 5000 years later and we're still all doing it. It hasn't been enough of a burden for you to avoid this place after 14 years and 12331 karma.

The way you've carried yourself on this thread indicates to me that you either don't understand other people's relationship to writing and why it is better than speech for them, or you are simply unempathetic.

> Speaking to people in a meeting allows them to emote, express difficulty of understanding, understand the sentiment and priority of what they're hearing -- and most of all, it allows them to listen rather than read. People speak at a much lower information density, and this is a less taxing form of communication.

Unless you have an intellectual disability, you can pay enough attention to the written word to get what you need out of it. Speaking is just as much a skill as writing. Who hasn't been in a meeting where the speaker is so boring, dull, or just bad at communicating that we zone off, go to another tab, and end up missing details? At least with writing I can go back and see what I missed. I can check myself.

I have ADD and a speech impediment. It is harder for me to pay attention to someone speaking, especially if they are boring, than it is for me to pay attention to a document. If I skim a document and miss something, it's all still right there in front of me. I can buckle down and read the whole thing. I can't replay a conversation. And vice-versa. With writing, I can gather my thoughts, think through what I'm trying to say, and present everything at once as a complete package that can stand on its own. Who hasn't lost a train of thought... or forgotten the word for something... or has a foggy brain and can't seem to remember an important detail? With writing, all of those things happen in the process of creation and get pruned out and fixed in the process of publishing (I use this word loosely).

---

The other thing I really wanted to comment on is the wild idea that is somehow okay for your manager to take your work, pass it through an LLM, and then present it to others as if it was your work. Like, what?!?!

I don't know what model you're using but AI lies. It lies all the time. It has no understanding. OP shows that because the AI generated overview of his work was full of hallucinations. The fact his manager didn't come back to him and talk to him about his documentation and offer feedback is crazy. AI came and gave everyone a taste of a lighter workload and instantly adults with 20+ years of experience unloaded their minds and started acting like vessels.

If I was that manager, I would be deeply embarrassed and ashamed.

[1] https://fs.blog/an-old-argument-against-writing/

[mjburgess]

So you prefer writing. Either way, writing is dying. It's dying because speaking and meeting can now be transmitted as easily. This itself should, empirically, demonstrate the point. The podcast killed the book, the meeting killed the memo. All around us writing is dying, and writing no one wants to read even more quickly.

Soon, in my view, writing will be seen as an instrumental intermediate artefact for technical or creative workers which is rarely shared and rarely read by anyone else. In other words, all writing will become checklists and scripts. Just as books became podcast scripts, and memos became meeting agenda.

I believe this is because writing and reading was, and is, a great burden to many. If you have some other explanation, so be it. It won't change the direction of the culture.

Prepare, I guess, to read more transcripts.

[nradov]

Another way of looking at that is that if writing is dying then doing it well will become a key competitive advantage. Organizations with culture, processes, and hiring standards focused on effective written communication will be faster and more economically efficient than competitors that rely on meetings (or recordings of meetings). Really crisp writing is especially helpful when prompting an LLM.

[mjburgess]

Sure, it will become a more elite creative and technical skill.

[walterbell]

> the meeting killed the memo

Some AWS meetings require the memo.

> writing and reading was, and is, a great burden to many

Other terms for writing and reading:

  • transmission
  • thinking (@paulg essay)
  • memory RL (reinforcement learning)
  • advantage
  • moat

> read more transcripts

Transcripts are primary sources. Sufficiently valuable primary sources can inspire new sources, created by humans through a process that includes, but is not limited to, reading and writing.

[OkayPhysicist]

This is a staffing problem, not a human one. There's plenty of non-knuckledraggers to hire, sack the illiterate and hire some competent people.

[balamatom]

The problem is that non-knuckledraggers know bad words like "why" or "no", and are not afraid to use them.

Knuckledraggers, on the other hand, only know good words like "vibe" and "ew", and gladly tune into the gentle rocking back and forth of the (filter-)feeder.

[balamatom]

Thank you.

[estimator7292]

No. Someone replaced well thought out documentation with AI fabrications and let GP take the fall for it.

That is malicious and inexcusable. It's not on GP, the fault lies with the idiot that ran gold documentation through the bullshit machine. Don't blame someone who was wronged, that makes you a malicious asshole.

[plumbees]

Without context of who these people are, yes perhaps malicious but perhaps not consciously so. Merits a frank conversation of indicating that the action of AI reinterpretation introduced errors that poorly reflect on OP's reputation and THAT deserves rectification. My worldy observation is that people in all industries lack training. It's all been offloaded to automated systems. And nobody is there to ask questions or think logically. The hospital staff doesn't understand why I'm angry when they call me using an AI to give me information and the AI is asking for so much PII. (You called me! You already have that information! How do I know you aren't a scammer?) They are not the users of their garbage. They aren't trained to serve the customers, they are trained to serve their managers and that disconnect is occuring everywhere. Why do the grocery baggers put heavy objects with the bread. This was never a think in the 90s and 00s, and now baggers are just not being trained properly. Like, wtf...

But yes do be on the lookout for malicous people, document, log and look for patterns... don't write it off, document.

[harvey9]

I can still see a path where the manager was stupid but not malicious. The manager sent on a document which he was too lazy to check at least had the right endpoints but left the GP's contact details on. I could also imagine intentional harm to GP's reputation was the goal, with really clumsy execution.

[antisthenes]

Either way, that person should not be managing anything.

And if it was an honest mistake, they need to come out and apologize both to the IC and to the team that is using the documentation.

[slava_]

I think it says a lot about micromanaging practice broadly. the person assigned for a task should be fully trusted and accountable. the manager could've criticize writing, recommend using LLM, but not interfere. what they've done shows lack of trust and responsibility first.

[plumbees]

Many mangers shouldn't be managing anything.

[neutronicus]

It's possible the receiving team may have complained about OP's writing before, too.

I will say, though, that I think the manager would have done better to encourage the recipients to opt-in to using a LLM to expound on specific points of confusion so that they'd have the actual source document in hand.

[ehaliewicz2]

"Perhaps you should ask the manager why he passed it through AI."

Because they were lazy and disrespectful, done.

[krageon]

It's kind of hilarious that saying "maybe he wasn't capable of reading comprehension" is supposed to be some sort of reasonable basis to have taken another unforgivable action on.