[Nml-wg] [NM-WG] First draft of NML Schema document

[Freek Dijkstra]

Jason,

Thanks a lot for your review! You made a lot of good suggestions.

Jeroen was just poking me off-list about adding a few examples to the
descriptions, in particular for Adaptation and for Labels.

So far my take has been to not include examples there, but include them
in the Examples chapter instead. The reason is twofold: first of all,
the descriptions are normative, the example informative. Secondly, there
is a bit more room for text in the Examples chapter. I usually never
understand a new concept until I have seen TWO examples. Only then, the
general pattern starts to dawn on me. So I prefer two examples per
definition.

That said --- I just hope that Jeroen does whatever makes the document
more readable. If adding examples makes it easier to read and implement,
I support that.

For the record, here is a list of examples I still like to include in
the Examples chapter, because they don't seem obvious to me at first:

* distinction between Topology and Node
* VLAN description with noReturnTraffic
* subTopology
* patch panel
* media convertor
* adaptation
* serial compound links (and importance to use directions)
* example explaining the relation between version and Lifetime. Imagine
that a link will have a planned downtime next week between 2 AM and 4
AM, but I now know it will be between 2 AM and 5 AM. Explain how to
update this information.
* Add example, explaining how to distinguish between what is configured
and what can be configured.

Regards,
Freek