| From: | Matemática A3K <matematica(dot)a3k(at)gmail(dot)com> |
|---|---|
| To: | Daniel Gustafsson <daniel(at)yesql(dot)se> |
| Cc: | Xavier Fischer <xavier_fischer(at)hotmail(dot)fr>, "David G(dot) Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com>, "pgsql-docs(at)lists(dot)postgresql(dot)org" <pgsql-docs(at)lists(dot)postgresql(dot)org> |
| Subject: | Re: Introductory docs-hacking task: Example markup |
| Date: | 2026-11-17 03:00:37 |
| Message-ID: | CA+FDnhK-Ovhahn6DM2B7BNtsv9+YskeyiR_66wF5TQ0pdOmxyg@mail.gmail.com |
| Views: | Whole Thread | Raw Message | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-docs |
On Thu, Nov 12, 2026 at 9:33 AM Daniel Gustafsson <daniel(at)yesql(dot)se> wrote:
>
> > On 12 Nov 2026, at 08:33, Xavier Fischer <xavier_fischer(at)hotmail(dot)fr> wrote:
> >
> > On Wed, Nov 11, 2026 at 7:42 PM Matemática A3K <matematica(dot)a3k(at)gmail(dot)com<mailto:matematica(dot)a3k(at)gmail(dot)com>> wrote:
> > On Wed, Nov 11, 2026 at 9:29 AM Daniel Gustafsson <daniel(at)yesql(dot)se<mailto:daniel(at)yesql(dot)se>> wrote:
> >>
> >> I will argue that no markup should be used for examples. The goal of
> >> an example is to help readers understand a general functioning by
> >> seeing a particular one. As such, they should be part of the prose
> >> that explains the functioning, not an independent element to be
> >> indexed. The only value I currently see in having a delimited or
> >> encapsulated example is the ability to skip it if you already got it
> >> from the explanation prose.
> >
> > I disagree with this: sometimes you want to search for examples of a construct, and having it indexed can avoid scrolling and makes clear that there's a dedicated section. I tend to do that when programming and it's useful to have a dedicated section to jump in directly.
> > There are some short examples in the middle of the main prose, not worth a section on their own.
>
> This aligns with my thinking. There might be cases where the example can be
> made part of the prose but in general I think technical documentation is
> improved by having separate and indexable examples.
I think the problem is the lack of documentation guidelines, and it is
not clear how to set them.
Once you define a guideline, then, you have a rule to make the doc
adhere. Different parts of the documentation follow different rules,
which one is the best? No answer, only that one should be chosen to
give shape. Consistency is defined through rules, without rules, there
cannot be defined "a deviation", or an inconsistency.
Once there is mechanism of defining guidelines, then, which guidelines
to use can be discussed.
The lack of defined guidelines makes any attempt to "move" the
documentation in some direction to "drown". Every argument makes sense
under some guideline, then, they get confronted, and then, nothing
happens. So, the documentation "doesn't move", it seems to be frozen.
Defining such mechanism should be the priority.
> One benefit to having proper markup is that the code in the examples can be
> extracted and tested against the current codebase to ensure no example code has
> become incorrect.
In other threads, it has been stated that the examples do not
necessarily run, questions have been routed with that. That's another
guideline, which one should be followed? See the problem?
> --
> Daniel Gustafsson
>
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Vinay Manikanda | 2026-11-17 03:44:57 | Re: Introductory docs-hacking task: Example markup |
| Previous Message | Laurenz Albe | 2026-11-16 15:21:01 | Re: OS system version upgrade (glibc / libicu version change) |