Adding "best practices" section

[azarboon]

Hi. I'm thinking to add a "best practices" section. This way readers can get list of best practices in the main page without the hassle of going through several articles. How does it sound? If maintainers support this idea, I can start it. @koppor

[socadk]

Thanks for the suggestion @azarboon. Can you describe your proposal in some more detail please: do you think of a new page? how would its content be curated/quality-assured?

[azarboon]

Thanks for the suggestion @azarboon. Can you describe your proposal in some more detail please: do you think of a new page? how would its content be curated/quality-assured?

Thank you. I was thinking about a new section in the main page titled as "best practices". But we can create a new page and link it in the main page.

Content will be based on existing articles and some other blogs. I can initiate the first draft and others can improve it. Once the maintainers endorse it, it should be good enough. And as always, we keep it open for further improvements.

Please let me know your advice.

[azarboon]

@koppor what's your advice?

[koppor]

Sure, go ahead!

[socadk]

@koppor @azarboon I thought about the proposal a bit more... I am not sure whether a "one size fits all" page with agreed upon good or best practices is feasible to create and maintain: Contexts and cultures differ, preferences and requirements differ. I suggest to move all pointers to good or best practices to a new page, possibly pointing at selected highlights and a disclaimer that we are merely pointing at advice, not endorsing it.

[azarboon]

@koppor @azarboon I thought about the proposal a bit more... I am not sure whether a "one size fits all" page with agreed upon good or best practices is feasible to create and maintain: Contexts and cultures differ, preferences and requirements differ. I suggest to move all pointers to good or best practices to a new page, possibly pointing at selected highlights and a disclaimer that we are merely pointing at advice, not endorsing it.

Sounds good.

[koppor]

We might need a scope clarification. Maybe, "decision making" is too borad for this repo. We might provide some initial pointers (e.g., https://medium.com/olzzio/a-definition-of-ready-for-architectural-decisions-ads-2814e399b09b), but cannot claim "completeness" in this field. "decision caputring" is more in the scope of this repository.

[azarboon]

We might need a scope clarification. Maybe, "decision making" is too borad for this repo. We might provide some initial pointers (e.g., https://medium.com/olzzio/a-definition-of-ready-for-architectural-decisions-ads-2814e399b09b), but cannot claim "completeness" in this field. "decision caputring" is more in the scope of this repository.

Interesting. I have to go through that link in detail. However, let's not get stuck in analysis paralysis. I can make the first draft and we can refine it and reiterate.

Before working on the draft, please finalize my other open PR. Then we can proceed with this one.

[koppor]

Interesting. I have to go through that link in detail. However, let's not get stuck in analysis paralysis. I can make the first draft and we can refine it and reiterate.

To provide room for expirments, we changed the layout of the homepage (#58) and currently restructuring into separate sections. Shouldn't take long.

[azarboon]

@koppor can you please create a new page named "best practices" so we can start to work on this. Also please add "edit this page" to the new layout.

[koppor]

Also please add "edit this page" to the new layout.

Filed as #68

I think, we need to implement for ourselves as soon as we find time for that.

[koppor]

@azarboon Note that we do not want to add "realy" content to the page; "just" links. (See #55 (comment)). Thus, if you have in mind to describe a concrete "good" practicse for ADRs, please craft the text on another site and we can link it when resolving this usse.

[azarboon]

@azarboon Note that we do not want to add "realy" content to the page; "just" links. (See #55 (comment)). Thus, if you have in mind to describe a concrete "good" practicse for ADRs, please craft the text on another site and we can link it when resolving this usse.

I was thinking about a concise summary of best practices (a long with links for further) to save readers' time.

[koppor]

I was thinking about a concise summary of best practices (a long with links for further) to save readers' time.

Please have an eye on a sound order of your summary entries and high cohesion between lists. -- How about adding the list at https://adr.github.io/ad-practices/#third-party-articles ?

Looking ahead, it might make sense to start another GitHub repo/page for this. Please note that we do not want to endorse any particular practices here; we are reluctant to use the term "best practices", maybe "good practices" is a little more fitting?