On Mon, 2025-04-07 at 09:07 +0000, Stefan Schmiedl wrote: > Wearing my documentation writer's hat, I agree that the information given on > one page need not be repeated on another one, especially if it's already > cross-referenced. > > However, with my documentation reader's glasses on, I would have liked to see > that data there, as it would have allowed me to file subscripts under > "brackets, mostly 1-based, slices [a:b] are closed intervals" and move on. > > As it is, I needed to follow the link to the array page, then to the section > "Accessing", where I encounter "Now, we can run some queries on the table", > which implies that I need to at least scan content somewhere above the > current > point to learn about the table structure. Only then I reach the bit about the > first index. > > Pages in part I and II (at least, I have not really gone into III and IV) > feel like > they're meant to be read completely from top to bottom, not topical like a > lookup > in the excellent Reference where I usually can find answers to my questions by > reading a few lines in the description of the option I'm unsure about. > > As such, I'd have appreciated the additional information as it would have kept > me in the flow of the page, a flow that its author has worked hard to set up > for me.
There is always room for improvement. It would be great if you could put on both of your hats and come up with a patch that implements the rather invasive change you are envisioning. Then we can see if it feels better overall, and we have a concrete basis for a discussion. Yours, Laurenz Albe
