search

dev-cycles / contextive

Get on the same page.
https://contextive.tech
MIT License
210 stars 5 forks source link

Seeking Advice on Best Practices for Integrating Contextive with DDD and Company Documentation #67

Open BudHimself opened 1 week ago

BudHimself commented 1 week ago

Hello Contextive Team,

I'm exploring the idea of incorporating Contextive into our development process, particularly to reinforce Domain-Driven Design (DDD) principles through a shared glossary.

Our organization utilizes Notion for documentation, which includes a user-friendly interface for maintaining a business glossary. We're considering how best to bridge the gap between Notion and our codebase where Contextive would reside.

Two potential approaches have surfaced:

  1. Notion-First Approach: Utilize Notion’s UI to curate the glossary database and then develop a tool or script to generate the Contextive YAML definition file from Notion for use in our repository.

  2. Repository-Ownership Approach: Have the development team directly manage the Contextive YAML definition file in our repository, and then render a view of this glossary in Notion for the broader team.

In the spirit of DDD, which approach would you recommend to ensure alignment and ownership of the ubiquitous language across both technical and business teams?

This inquiry is more about the strategic integration of DDD methodologies with tooling like Contextive rather than the technical use of Contextive itself. I would appreciate your insights on this.

Thank you for your time and assistance.

Best regards

chrissimon-au commented 1 week ago

In the spirit of DDD my recommendation would be to have the official definitions in the repo (as written by the developers) and have a mechanism to push them into a more broadly accessible location to ensure there is a feedback loop for them.

My rationale is that historically, domain experts and BAs would write specifications and developers would implement them. This is a one way flow of information and was wrought with risk of misunderstanding - misinterpretations are only discovered later, during testing.

With modern DDD practices like event storming and domain storytelling, developers are part of the analysis, discovery and design process and have the opportunity to check their interpretation and understanding "on the fly".

I think that having devs write the terminology definitions and then publishing them for comment/feedback is a wonderful way to check that developers have interpreted the domain appropriately.

If non-devs believe the definitions are not correct, they should not just modify them - rather they should have a conversation with the developers to help them understand why they are not correct, and then the developers should update the definitions to demonstrate their new interpretation.

There is one exception to this - which is the examples field. Non-devs should be able to contribute sample sentences of the words being used in realistic scenarios.

BudHimself commented 1 week ago

Ok, it is very clear.

In internal we had discussion about both solution, but i think we will go in the 2nd. Developer own the definition and have to take the ownership on this documentation.

In second hand, we will add a Notion view of this documentation for external people of the team.

Thank you for your advices.