Cleanup and slim down design guidelines document

[shilpa-padgaonkar]

Problem description
We have over time added several rules, naming conventions etc. in the design guideline document that are "must" for Camara subprojects to follow and incorporate in their spec files. These rules are spread out over different sections of this long document. This can easily lead to contributors (especially new Camara contributors) to easily miss out on important rules/constraints, thereby leading to considerable rework and efforts, both for the review team and the contributors.
We also intend to improve the linting rules to ensure that most of these guidelines and constraints can be precisely validated against.

Expected behavior
This issue proposes to clean up and slim down the design guidelines document, making it more similar to the ICM security and interoperability profile doc which focuses on specifying the precise points/guidelines that should be followed by the subprojects when designing their API spec files and the more generic recommendations and best practices being referred by external links (instead of copying or duplicating material in the doc from external sources). As this clean up and its review will take time, the proposal is to bring this activity in scope for the next Camara meta release.

Alternative solution

Additional context

[bigludo7]

Hi @shilpa-padgaonkar
Following your recommendation, we can have all the part12 about the subscription notification & events in a dedicated document and just refer it from the API design guideline with a link. This is your proposal?

As I volunteer to update this part, waiting for guidance before triggering a PR (cc: @rartych )

[shilpa-padgaonkar]

@bigludo7 Sorry for the late reply :(

I would like to propose 3 changes as a part of this issue:

Change1:
Create a document with the sections of an OpenAPI doc

• OpenAPI Object
• Info Object
• Servers Object
• Paths Object
• Components Object
  etc.
  and document the Camara specific changes/requirements under each of these sections.

Change2:
Have a separate document for topics which are quite big, such as subscriptions and refer these alongside the above section doc with links in the main doc. This exactly matches to your remark above and happy to know that you would like to volunteer here :)

Change3:
For the third change, I would give the example of section
in our doc. In this guidelines' doc, such sections (which are mainly informative or best practices) could simply add an external link which could be an official document source for DDD etc. instead of duplicating the entire content in our doc unless we are specifying something that is custom in Camara.

WDYT?

[bigludo7]

Hi @shilpa-padgaonkar
Looks good for me !

Practically for the Subscriptions&Notification part do you & @rartych prefer that I split this part first and then consider all the comments for the 0.5 or that I work on the current doc and we'll do the split before the release?
Latest option is probably easier but both work for me.

[shilpa-padgaonkar]

@bigludo7 As subscriptions content is (hopefully) consolidated in one section of our document, I guess either way is fine for me. @rartych WDYT?

[rartych]

Ideally, we should first focus on changes for 0.5 and then prepare the new shape of documents without changing guidelines. This way subprojects should have more time to adjust to new guidelines.
Let the alpha version include the most of PRs and the RC-1 propose changed document (and needed corrections).
In the meantime in this issue we can work on the ToC of the new guidelines document - here is the list of topics usually covered in API design guidelines.

[PedroDiez]

Hi!

@shilpa-padgaonkar within Change1 is the idea to also cover mention for Error Guidelines?

[shilpa-padgaonkar]

@PedroDiez For Error guidelines I was not able to come to a conclusion, :) Not sure if this would again become too big a topic in itself and could be split as well or should we keep it in change1. If you have a preference, would be happy to hear it.

[shilpa-padgaonkar]

In the meanwhile, I at least start a draft PR which will include the chagne1 doc structure to start with.,

[PedroDiez]

@PedroDiez For Error guidelines I was not able to come to a conclusion, :) Not sure if this would again become too big a topic in itself and could be split as well or should we keep it in change1. If you have a preference, would be happy to hear it.

I can take the action for that part (i.e. analyze updates in errors section)