Re: Introductory docs-hacking task: Example markup

> 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.

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.

--
Daniel Gustafsson