walterkozlowski
commented
4 years ago @pgoyal01, I started reviewing and I have found quite a few issues with Chapter 1 Overview, that I think it is better if I document them here, before passing to the next chapters. I tried to pretend to be a newcomer without any prior knowledge about this document or other CNTT documents.
@rabi-abdel and @kedmison you may be interested in these observations as well, e.g. because of some unclear statements about versions and some issues with RM Principles which I discovered on my way.
Here we go:
Chapter 1 Overview
Comment #1: Acronyms and terminology:
There is no information or consistency regarding the first use of acronyms: in some cases they are explained (e.g. QoS in the 1.2 “Performance tuning” use case) but most of them are not (e.g. GRE, MLAG in 1.3 “Overlay networks”). Most of them are very well known in the industry but we need to have a more consistent approach. I suggest either define the acronym when it is first used in this document, or (better) make a comment at the beginning of the document that acronyms are defined in a glossary and provide a link to it. In some special cases (I would not include QoS into this category) it may be done both ways; for example, when this is a new acronym introduced into the industry by this document.
Looks like there are places where such definitions may be defined, Sec 1.3 Terminology refer to them but both links CNTT Reference Model and RA-1 Terminology DO NOT WORK (error 404).
Comment #2: Principles Sec 1.4 uses link CNTT Reference Model Principles to the one sentence long Sec 1.3 in https://github.com/cntt-n/CNTT/blob/master/doc/ref_model/chapters/chapter01.md#1.3 with a link https://github.com/cntt-n/CNTT/blob/master/doc/ref_model/chapters/chapter01.md#1.3 when clicking on the latter on we land in Chapter 2 Principles in RM. It seems quite a convoluted way and the reader ends up two links from the original text, probably at lost. A side comment: Sec 2.1 Overall Principles in RM need badly an update and refresh; e.g. Principle 9 explicitly forbids the use of SR-IOV (agreed when it uses PCI-PT but a nuance people may and will miss) while we have an exception process, which is not mentioned there. And few other issues (several of the principles are formulated like requirements not like principles, the text must be quite old by now). Sec 1.4 uses also another link CNTT Reference Architecture Principles which takes us back to the GitHub landing page with links to two reference architectures (Openstack Based and Kubernetes Based); I think that most readers will be completely lost; also it is circular reference because selecting Openstack we are back in the document we started but in a different place.. Also, Sec 1.4: a minor typo: in bullet points describing Four Opens “design” is the only one which uses a small not a capital as the first character. Btw: It seems we do not have any consistency writing OpenStack in some (most?) places and Openstack in others (see above).
Comment #3: OpenStack release Sec 1.5 CNTT OpenStack Release: Shouldn’t it be “This Reference Architecture document in its current version conforms to the OpenStack Pike release.” Rather than the current “This Reference Architecture document conforms to the OpenStack Pike release.” Later on we read ‘For ease, this CNTT Reference Architecture version can be referred to as "RA-1 OSTK Pike."’ We need to be clear whether we are talking about the document, about the architecture or about a version (of what? Of a document? Or of Architecture?).
Comment #4: Document Organisation The first sentence of Sec 1.6 is “The Reference Architecture requirements and the traceability where in this document the requirement is addressed is documented in Chapter 2.” contains a typo “is addressed is documented”. The traceability part of this sentence is a bit unclear, particularly as in Chapter2 Sec 2.2 “Reference Model Requirements” we have only one sentence “Traceability to Reference Model.” and that’s it! Back to the first sentence of Sec 1.6: I would propose something like “ Chapter 2 defines the Reference Architecture requirements and, when appropriate, provides references to where these requirements are addressed in this document.” Typo: “items, Please note that”, should be “items. Please note that”. The sentence “Chapter 8 identifies certain Gaps that currently exist and plans on how to address them.” is a bit misleading as Chapter 8 only make a promise to do such plans saying “Once gaps are identified, the next step will be to propose a plan to address these gaps.” and indeed Chapter 8 does not provide such plans yet (except of some hints what might be possible or not, in some cases; no such hints in other cases). Btw: why “Gaps” in Sec 1.6 (capital “G”) and “gaps” (small “g”) in Chapter 8?
rabi-abdel
pgoyal01
iangardner22
E2E review.