News for hackers. Stuff that matters.
Re:How to Write in Plain English by omnicognate on Tuesday August 25, 2020 @05:34AM (#24269538)
Overflowing that buffer really does feel like a stack overflow, too. Your whole mental state just suddenly disappears in a puff of smoke.

This resplendent sentence in the Vulkan spec did it to me the other day:

The layout of subresources of images on other logical devices that are bound to VkDeviceMemory objects associated with the same underlying memory resources as external memory objects on the lost device becomes VK_IMAGE_LAYOUT_UNDEFINED.

I got about half way through and suddenly discovered I didn't know where I was, what year it was or my name.

Re:How to Write in Plain English by gjm11 on Tuesday August 25, 2020 @04:27PM (#24275724)
Trying to rewrite that sentence so it's comprehensible is an interesting exercise. How about this?

(I don't know anything about Vulkan, and there is some ambiguity in the quoted sentence, so I've given a few different versions with different meanings. Note that the ambiguity is not necessarily a flaw in the quoted sentence -- it may be perfectly unambiguous, albeit very unclear, to anyone with any knowledge of Vulkan.)

If a device is lost, the subresources of some images on other logical devices may have their layout become VK_IMAGE_LAYOUT_UNDEFINED. This happens if the VkDeviceMemory object to which the image is bound is associated with the same underlying memory resources as an external memory object on the lost device.

... or, if an image isn't necessarily bound to exactly one VkDeviceMemory object, ...

If a device is lost, the subresources of some images on other logical devices may have their layouts become VK_IMAGE_LAYOUT_UNDEFINED. This happens if the image is bound to a VkDeviceMemory object which is associated with the same underlying memory resources as an external memory object on the lost device.

... or, if it's the other logical device bound to a VkDeviceMemory object rather than the image:

If a device is lost, the subresources of images on other logical devices may have their layouts become VK_IMAGE_LAYOUT_UNDEFINED. This happens if the other device is bound to a VkDeviceMemory object which is associated with the same underlying memory resources as an external memory object on the lost device.

Or maybe a slightly different structure. "If a device is lost, and some VkDeviceMemory object is associated with hte same underlying memory resources as an external memory object on that lost device, then all subresources of any image bound to that VkDeviceMemory object have their layout set to VK_IMAGE_LAYOUT_UNDEFINED."

But I can't help thinking that this really wants a diagram. Nodes for the logical devices, the images, the VkDeviceMemory object, the "underlying memory resources", the external memory object. Labelled arrows for relationships like "bound to", "has as underlying memory resource", "is a subresource of", etc.

And it seems as if this business of "having your layout set to VK_IMAGE_LAYOUT_UNDEFINED" deserves a name. (Naming things is a powerful general technique for reducing cognitive stack overflows.)

"Under some circumstances, the memory resources associated with an image may be invalidated, in which case all subresources of the image will have layout VK_IMAGE_LAYOUT_INVALIDATED and [explain here the consequences of that]. In this case, the image is said to be layout-invalidated. " ... And then later, when talking about lost devices, you say "If a device is lost, images on other logical devices may be layout-invalidated. This happens when the image is bound to a VkDeviceMemory object, and that object is associated with the same underlying memory resources as an external memory object on the lost device."

Re:How to Write in Plain English by athriren on Tuesday August 25, 2020 @07:19PM (#24277403)
Most of the time if someone speaks to me in a non-casual context, my brain is constantly navigating the pathing process you describe. Although language is often not ambiguous, most people do not make their meaning as explicit as necessary to avoid confusion.
Re:How to Write in Plain English by nicbou on Tuesday August 25, 2020 @05:45AM (#24269607)
This is how I felt while reading philosophy essays. I'm not even sure half of those are even saying anything.
Re:How to Write in Plain English by vidarh on Tuesday August 25, 2020 @05:51AM (#24269642)
A lot of philosophy essays are written as part of the writer being in the process of trying to figure things out for themselves, without quite having gotten there yet.
Re:How to Write in Plain English by formerly_proven on Tuesday August 25, 2020 @06:36AM (#24269886)
It really shows, just like docs written by someone who hasn't actually understood what they're writing about yet.
Re:How to Write in Plain English by darkerside on Tuesday August 25, 2020 @07:31AM (#24270238)
This is why second drafts exist
Re:How to Write in Plain English by brain5ide on Tuesday August 25, 2020 @07:59AM (#24270450)
We had this joke.

A meeting of faculty heads is taking place. The topic - funding. The chairman says: "Hey, physicists, why are you so expensive? You need all those gadgets and materials to perform your experiments. Look at the mathematicians. All they need to produce a research paper are a box of paper, a box of pencils, and a trash can." "We don't even need trash cans, sir." announces the dean of Philosophy.

Re:How to Write in Plain English by MaxBarraclough on Tuesday August 25, 2020 @08:25AM (#24270596)
I guess they have an equivalent repository with roughly the same impact factor.
Re:How to Write in Plain English by jagged-chisel on Tuesday August 25, 2020 @09:25AM (#24271067)
The janitor concurs.
Re:How to Write in Plain English by dvtrn on Tuesday August 25, 2020 @12:31PM (#24273096)
“Hallelujah”-Coen, Leonard.
Re:How to Write in Plain English by ajarmst on Tuesday August 25, 2020 @03:46PM (#24275263)
*Cohen (or כֹּהֵן if you're feeling particularly pedantic.) :-)
Re:How to Write in Plain English by dvtrn on Tuesday August 25, 2020 @05:51PM (#24276595)
Thank you :)
Re:How to Write in Plain English by lallysingh on Tuesday August 25, 2020 @10:39AM (#24271779)
That's a lot of qualified noun phrases. This should just be an s-expression. It's already one, honestly, but without the right parenthesis.

(becomes (qualified (layout of subresources of images on other logical devices) (bound . (same-memory-resources (VkDeviceMemory objects) (external memory objects on the lost device)))) VK_IMAGE_LAYOUT_UNDEFINED)

Will natural-language tools eventually help us turn these puddles of nouns into reasonable sentences?

Re:How to Write in Plain English by kwoff on Tuesday August 25, 2020 @10:29AM (#24271687)
We have a small number of "slots" of short term memory. I wonder how smart we'd be if we had twice as many slots.
Re:How to Write in Plain English by grugagag on Tuesday August 25, 2020 @10:50AM (#24271899)
I don’t think we’d see the difference if everybody had roughly the same number. Ive seen people who have a few more slots than average and it appears quite inpressive, they keep on stacking up when I already overflow. It’s probably got to do with how they chunk their information though.. But a piece of paper and a pencil can do wonders
Re:How to Write in Plain English by kube-system on Tuesday August 25, 2020 @11:26AM (#24272306)
Paper and pencil is like writing to swap.