Re: Get rid of "Section.N.N.N" on DOCs - Mailing list pgsql-hackers

On Thu, Jan 1, 2026 at 7:21 AM Marcos Pegoraro <marcos@f10.com.br> wrote:
>
> Em qua., 31 de dez. de 2025 às 21:03, Robert Treat <rob@xzilla.net> escreveu:
>>
>> The surrounding text already gives context as to what we will find in
>> those linked references,
>
>
> My intention here is to read and rewrite all texts that need revision, so the surrounding text will probably change
aswell. When reading documents, we need to open the link or hover the mouse over it to read the link to see that that
isnot what we want, before returning to reading, so it's quite common to get lost in the text because of this back and
forth.
> Instead of
> There are currently four procedural languages available in the standard PostgreSQL distribution: PL/pgSQL (Chapter
41),PL/Tcl (Chapter 42), PL/Perl (Chapter 43), and PL/Python (PL/Python). 
> Wouldn't it be better to have a paragraph like this ?
> There are currently four procedural languages available in the standard PostgreSQL distribution: PL/pgSQL, PL/Tcl,
PL/Perland PL/Python. 
>
> So I don't care if that link is a section, a appendix, a chapter, I'm sure I'll go there only if I really want.
>

I do understand your intention, and I don't think it is better. You
say you will only go there if you really want, but it's harder for
readers to know if they really want to go there when you remove the
information delivered via those chapter numbers. We help the reader
understand that things like plpgsql and pltcl are so close to our
current topic that they are in the very next chapters, but writing
your own pl isn't as relevant to the current reading given we've put
it farther away; in other words there is a lot of material between
here (chapter 40) and writing your own procedural language (chapter
57) that we think you'd probably want to read about first if you are
just reading through rather than searching for something specific. And
while you say you don't care if the material is in another chapter or
appendix, it does convey something to the reader that we think this
information can be completely sectioned off from the main manual by
itself. And I would note, even you did not remove the appendix heading
in your previous example ("Appendix H: External Projects has
information..."), and it seems clear to me there would be information
loss if you had done so.

>>
>> But the numbers do provide some subtle clues as to the relationship of the
>> linked references to the page we are on AND other references within
>> that page.
>
>
> Well, if a link was written on that page, independently if it's a chapter, a GUC, a section, it's important for the
userto know. And again, I don't care if I'm jumping to a distant section or chapter, it's important to understand
entirelythe page I'm reading. 
>
> So, my intention here is to provide the user with continuous reading. If I read a paragraph with links but it's
displayedas if it were in a book without footnotes, it gives me a much faster and easier reading experience. If I have
tostop my reading to open other links because I don't know if they're important or not, or also bad ignore some words,
thereading isn't as productive. 
>

What you're proposing makes more sense if we were writing prose or
blog posts or similar works, but we're making educational
documentation that serves as a user manual and reference guide.
On the web, where a link can take you to any other place in the world,
giving the reader some sense of directions can be extremely grounding,
and chapters, sections, and appendexis aren't some kind of
afterthought; for what we're building, all those pieces matter.


Robert Treat
https://xzilla.net