Differentiation between standards and decision records (#352)

[cah-hbaum]

Like it's described in #352, we want to better differentiate between Standards and Decision Records.
The main points that were made is that both document types are put in the same location, which makes it hard to differentiate (especially for new or external people), since the difference can only be seen when opening the documents.
Also as mentioned by @markus-hentsch, the standard template doesn't necessarily fit for Decision Records, since they're not setting a standard, but merely describe an overall decision. Therefore, the template for this type of document can be shortened.

I would like to have a discussion in the comments if this template split is alright and also if the structure of the templates is acceptable.

[cah-hbaum]

To start a discussion on this (and take the suggestion of @markus-hentsch from #352):

Is a versioning of Decision Records necessary?

I can understand both cases. On one hand, the Standards and DRs of SCS are designed a bit like RFC standards, meaning that certain standards supersed previous ones, which is mostly indicated by the version number of a standard. This is good to keep track of changes and explain certain "historic" decisions and maybe old setups that still use older standards. The same would be true for Decision Records.
On the other hand we must acknowledge that Decision Records are not really binding and therefore are not required to keep track of their changes.

[anjastrunk]

IMO, we do not need versioning in DR. Most of them will not be touched after they where written. Is suggest to create e new DR, if the old one must be reconsidered, I suggest to open a new DR referencing the old one.

[mbuechse]

We can certainly discuss these templates, and I think the proposal has merit, but these documents are only supplemental to the actual standard scs-0001-v1, which I guess needs to be changed as well?

[cah-hbaum]

We can certainly discuss these templates, and I think the proposal has merit, but these documents are only supplemental to the actual standard scs-0001-v1, which I guess needs to be changed as well?

Yes the standard would need to be changed as well. I just wanted to present this template and create some consent before starting to work on the document.

[anjastrunk]

LGTM.

[cah-hbaum]

As discussed in the last SIG Standardization/Certification meeting, we will update and adapt this PR until the next meeting (including the standard).
We will than see, if there are major objections against it and either merge it or reject it entirely.

[artificial-intelligence]

but these documents are only supplemental to the actual standard scs-0001-v1, which I guess needs to be changed as well?

I thought about this as well and I tend to agree with you.

[artificial-intelligence]

We will than see, if there are major objections against it and either merge it or reject it entirely.

Could you explain in more detail what this means? As it is spelled out this way I wonder if this introduces a new way of reviewing this document? Because if this is not the motivation, I don't understand why it is written down at all, when nothing changes?

Apologies if I'm missing context as I was not present in the last meeting. That being said, it should be possible to review a standards document without needing additional context from any meetings. If such context is needed, I think at least a link to the minutes would be courteous to provide.

However looking at the minutes there isn't any new decision in there regarding this document, only a call for reviews.

So I'm left puzzled to decrypt what the meaning of the above should be.

Any explanations would be appreciated.

Thanks!

[cah-hbaum]

We will than see, if there are major objections against it and either merge it or reject it entirely.

Could you explain in more detail what this means? As it is spelled out this way I wonder if this introduces a new way of
reviewing this document? Because if this is not the motivation, I don't understand why it is written down at all, when
nothing changes?

Apologies if I'm missing context as I was not present in the last meeting. That being said, it should be possible to review
a standards document without needing additional context from any meetings. If such context is needed, I think at least
a link to the minutes would be courteous to provide.

However looking at the minutes
there isn't any new decision in there regarding this document, only a call for reviews.

So I'm left puzzled to decrypt what the meaning of the above should be.

Any explanations would be appreciated.

Thanks!

Yeah, tbf the meeting notes on this topic are a bit "sparse", probably because it was done towards the end with little time left.
So to give some more context to this overall; this whole issue was started by @markus-hentsch (not really present anymore due to changes in his workplace) and me, because we we're not satisfied with different aspects of the standards.
For me it was primarily the mixing of Standards and DRs in the same folder and with the same formatting, which makes it harder to differentiate the documents on first glance or while reading them. Basically the only real indication a person has for differentiation is in the header of the document. Which is ok, but not perfect, especially if you need to go through multiple documents or want to read up on standards in general.

@markus-hentsch had more of a problem with the generally equal structure of both document types. In his opinion (and I must agree), a DR doesn't have the same purpose as a Standard and therefore doesn't need the same structural points in his document.

I tried to put these points into a new template (and added some fixes for the old template) and we started to discuss this in the last SIG Standardization/Certification meeting.
The consensus (at least as far as I remember) was that nobody had a really strong opinion for or against these changes. In general, the gist from the meeting was: "You can provide these templates, adapt the tests and standard relevant to them and then we can try them out on a standard and DR and see if the new structure generally provides improvements. If this is the case and nobody has objections later on, we can think about accepting this PR."

Personally, I would try to create a standard and DR for SovereignCloudStack/issues#470 and try to provide an example via this issue.
If it doesn't work out, I need to change it again, but I guess this is only a small price to pay.

[artificial-intelligence]

overall I'm honestly not really happy with the review experience here as a reviewer, because the change, when diffed locally vs the old standard mixes the actual content of this PR with unrelated reformatting fixes, spelling fixes and even editorializing unrelated parts of the standard, which made this more tedious to review than it needs to be.

I would prefer it if we could, in the future, split up spelling and formatting bugs into their own respective PRs. But maybe that's a minority opinion.

On topic of the actual adjustments being done, see my comments.

[markus-hentsch]

I'd like to reiterate on my original suggestion for DRs as described here: #352 (comment)

It seems that the current implementation of the DR template in this PR aims to record a single decision only (judging from the headline structure).

I'd like to rework the DR template to resemble some kind of decision history log with a repeatable snippet for decision entries. As an example see the DR section of the Domain Manager Role standard.

Was there any discussion about this that I missed while I was away or was that simply not considered yet?

[cah-hbaum]

I'd like to reiterate on my original suggestion for DRs as described here: #352 (comment)

It seems that the current implementation of the DR template in this PR aims to record a single decision only (judging from the headline structure).

I'd like to rework the DR template to resemble some kind of decision history log with a repeatable snippet for decision entries. As an example see the DR section of the Domain Manager Role standard.

Was there any discussion about this that I missed while I was away or was that simply not considered yet?

This whole issue was my best-effort solution after you left, because TBH I didn't find the original idea you mentioned above anymore. I don't know if it was written down anywhere, but I couldn't remember all the details.

And about not doing Versioning for the DR files, that is probably possible, but I didn't want to include such a big change, since that would mean more rewriting of the initial standard scs-0001 and that would've been more hard to get through. I also wasn't 100% sure, if I wanted to include it, since I also can see the usefulness of versioned files.

[mbuechse]

I want to approve this, because I (have come to) like the general direction. But want I would like to see:

• make the change in place in scs-0001-v1
• make the changes to current documents less intrusive (don't demote a lot of sections)

[cah-hbaum]

I want to approve this, because I (have come to) like the general direction. But want I would like to see:

* make the change in place in scs-0001-v1

* make the changes to current documents less intrusive (don't demote a lot of sections)

Ok I will try to do that.

Edit: Added the changes to the scs-0001-v1 document and made less changes to the current standard documents.

[josephineSei]

I just have two questions on this:

1. Why do you want to specify an author? I thought, we want to provide the standards as community so from my point of view, there will not be any single author.
2. Which date should be stated here? The date of the first merge? The date of a standard going from draft to another state?

Thank you for answering these questions

[mbuechse]

I have the same questions.

1. I'm not opposed to stating the authors, but it must be clear how to specify multiple authors.
2. If we do state a date, it must be yyyy-mm-dd

[garloff]

And if we do a date, we'd use YYYY-MM-DD of course.
But indeed, we may not need one ...

[cah-hbaum]

I have no hard feeling for both options, I just saw that some documents contained authors and sometimes a string called "version" (e.g. here) with a date can be found.
There is also some other metadata (e.g. in https://github.com/SovereignCloudStack/standards/blob/main/Standards/scs-0100-v1-flavor-naming.md) that doesn't seem to conform.

I guess scs-0001 doesn't forbid additional metadata fields, but its kind of all other the place and doesn't make a good impression to me.

And as I said I can remove both lines if a decision is undertaken to do it. At least the author I find kind of useful, because even if the standard is provided by the community, the author (and its co-authors) would have the most knowledge, if someone has questions about the document.

author: Author1 <Mail or Github handle>[, Author2 <Mail or Github handle>[...]]

[mbuechse]

Suggested change

	author: Author <Mail or Github handle>
	date: DD-MM-YYYY

[mbuechse]

I will unblock this PR as soon as I get to it!

[mbuechse]

This whole thing is still giving me pause.

• The heading Standard/Decision still seems a bit awkward to me, even where it has been used before. We should find a better way.
• Decision Record could be interpreted in two ways (at least):
  • (a) a complex trade-off assessment, weighing multiple options, each of which (initially) appearing worthy
  • (b) a list of rather simple decisions such as how to name something
  • and our DR is a lot more (a) than (b) (or not b at all)
• The fields author and date are not covered by scs-0001-v1, and I think at least the date is expendable.
• We also need to cater for Procedural and Supplement documents.

[mbuechse]

I still have to think about this some more. I'm still not convinced, but I can imagine that you are on to something here.

[mbuechse]

Suggested change

	- A section containing the actual standardization decision. The naming for this is up to the standards
	author, since the flow of the document possibly changes the naming. We RECOMMEND naming the section _Standard_.
	- A section containing the actual standardization decision.

[cah-hbaum]

Changed in 6fb17a1

[mbuechse]

I still think this goes too far, but only by a bit. The changes I propose are intended to leave a bit more room for writers, but also for developing this further.

[mbuechse]

Suggested change

	- A _Terminology_ section which shortly describes terms used in the document, including possible abbreviations.
	- A _Terminology_ section which briefly describes terms used in the document, including possible abbreviations.

[cah-hbaum]

Changed in 6fb17a1

[mbuechse]

Suggested change

	- A section containing the actual standardization decision. The naming for this is up to the standards
	author, since the flow of the document possibly changes the naming. We RECOMMEND naming the section _Standard_.
	- A section containing the actual standardization decision.

[mbuechse]

Suggested change

	- A section containing the actual decision that is introduced. The section should also include
	reasoning for this decision. We RECOMMEND naming the section _Decision_.
	- A section containing the actual decision that is introduced. The section should also include
	reasoning for this decision.

[cah-hbaum]

Changed in 6fb17a1

[mbuechse]

I think @markus-hentsch somewhere remarked that there were no parts in italics/emphasized, but this is a counter example.

[mbuechse]

Suggested change

	author: Author <Mail or Github handle>
	date: DD-MM-YYYY

[cah-hbaum]

Changed in 6fb17a1

[mbuechse]

Suggested change

	author: Author <Mail or Github handle>
	date: DD-MM-YYYY

[mbuechse]

Suggested change

	Standard
	What is the essence of this standard? Adjust heading accordingly.

[cah-hbaum]

Changed in 6fb17a1

[scs-zuul]

Starting check jobs.
Warning:
Failed to create check run SCS/check: 500 Server Error: Internal Server Error for url: https://api.github.com/repos/SovereignCloudStack/standards/check-runs