How to link domain specifications with the code implementation without forcing domain expert to adopt any particular practice

Question

Our current business process is that the domain experts will write down the business logic in a Word document, and developers will try to reflect those logic as closely as possible with the implementation.

This process violates the DRY (do not repeat yourself) principle, and thus creates many problems that are associated with violating DRY principle.

There is no programmatical way of determining if the change in the domain document is correctly reflected in the code base. This forces very close-knit communication between the domain expert and the developer, which causes other problems such as the document resembling more of the tech specifications rather than the domain specifications and frequent meetings if any part of the document needs to be updated.

Note that I am a developer, and I am not looking to introduce a solution that requires an adoption of a software approach by anyone but me. I am trying to find a simple solution that can be handled by a single developer.

I've done my research and have encountered some suggested solutions such as domain specific language or domain driven design, but they don't fit my needs for the following reasons:

• DSL: This requires the adoption on the DE's part to use the DSL. I can use DSL to implement the domain logic using DSL, but this doesn't resolve the underlying problem of separation between domain document and implementation. Also, I do not want to limit domain expert's ability to express domain problem to specifically DSL. I want them to be able to use natural English.
• DDD: A bit better than DSL in that only the ubiquitous language needs to be developed, but this still requires explaning the concept of DDD to everyone involved.

In essence, I am looking for a simple solution that can be contained by a single developer. One ideal solution I was thinking was have some tool that can somehow annotate a section of the documentation to the specific code implementation, so that at least we have a brief visual cue of how well covered our documentation is.

Answer 1

Our current business process is that the domain experts will write down the business logic in a Word document, and developers will try to reflect those logic as closely as possible with the implementation.

This process violates the DRY (do not repeat yourself) principle, and thus creates many problems that are associated with violating DRY principle.

The problem here is retaining this word document as if it has meaning beyond when the programmer first consumes it.

If the programmer is creating a DSL or a ubiquitous language in DDD then the business logic should be something a domain expert is comfortable inspecting directly. It should also be free of anything technical that distracts from focusing on high level policy.

We're not at the point where you can force the domain expert to write actual business logic. But if you do it right they can read it and tell you if you forgot something or are doing something wrong.

So yes, that word document will get outdated. That's fine. It shouldn't be kept current. The business logic should be something your domain expert can print and doodle on. It shouldn't be something they author in word.

Answer 2

I honestly don't see an issue, in terms of process, with your current system. All that needs to be done here is a simple paradigm shift in how you guys treat and think about the documents that outline business rules.

The first change here is to forget about using these documents as some sort of analogue to code documentation. You are bridging a gap that needn't be bridged, and doing so is to everyone's detriment. Domain experts document the business requirements and processes that are important to the business. Other than using the Ubiquitous Language (which is formed at this level and permeates downward), these documents have nothing to do with your code base or it's implementation. Code documentation is technical by nature and shouldn't be mixed with rules that span process.

It seems like you guys are trying to find a middle-ground between Domain Expert and Developer in a way such that the experts can create some sort of pseudo-code that get translated into actual code. Additionally, you would like to impose rules on that process to ensure that the translation is not only happening, but is also correct. At that point, why not just have Domain Experts write the actual code?! The reason your job exists is so that Domain Experts can focus on the domain and you can focus on the code (the technical implementation). Currently, both roles seem to be focusing on the wrong thing (I suppose this is why you want an automated solution).

The second shift is, put simply, the business documents cannot be changed, only replaced. When a new document replaces an old document, the code base is changed to reflect the new rules. Fundamentally, this is just version control.

There will never be a good way to programmatically know if changes to a business document have been reflected in code (forget correctly). I'm getting queasy just envisioning the mess such a system would create. Better solutions can be found by taking a look at the process itself (introducing "tickets", for example). If this is such an important part of your business process, surely adding some simple infrastructure to manage it will be worth while. Including an automated testing suite can be very helpful as well.

And for what it's worth, close communication between domain experts and developers is a good thing.