Non-normative sections of the specification

Development & Maintenance
1

Scott @scottdixon has proposed that non-normative parts of the specification, such as examples and recommendations, should be removed from the bulk of the document that contains formal descriptions. The advantage of this separation is that it (arguably) makes the overall document more structured. The disadvantage is that examples and recommendations might be harder to follow when they are detached from the relevant context.

Currently, the spec draft is rich in intermissions, where rigorous descriptions are located right next to recommendations and such; for example, the DSDL chapter contains large sections dedicated to usage examples. Do we want to change that, and if so, how? Should there be an annex at the end? Or should we rather introduce a formatting or similar convention where non-normative sections would be highlighted in some way while keeping them in their place? I would personally prefer the latter, as that helps to keep related items close to each other.

2

One idea I’ve seen in some textbooks is to use a border and background color to highlight examples:

image
image783×435 62.9 KB

In our case we could put all non-normative sections into such boxes.

1 Like
3

I like this idea, it will make it easier to understand what should be considered the core specification.

In our case we could put all non-normative sections into such boxes.

I guess this is the best of both worlds. Both clearly expressing the specification and providing details to readers new to the specification.

1 Like