Comments on: Lean Architecture Principle #9: Comprehensible over comprehensiveness http://blog.xebia.com/2010/07/21/lean-architecture-principle-9-comprehensible-over-comprehensiveness/ Software development done right! Wed, 08 Feb 2012 14:41:38 +0000 hourly 1 http://wordpress.org/?v=3.3.1 By: KL http://blog.xebia.com/2010/07/21/lean-architecture-principle-9-comprehensible-over-comprehensiveness/#comment-95733 KL Wed, 28 Jul 2010 13:45:21 +0000 http://blog.xebia.com/?p=5020#comment-95733 There are a few typos in my previous comment ... In the paragraph "But I got..." : * change "business language" to "business documentation" * change "be read-only" to "not be read-only" * add a final dot In the last paragraph : * remove the second "also" * before "for automatic testing", add "for development, " There are a few typos in my previous comment …

In the paragraph “But I got…” :
* change “business language” to “business documentation”
* change “be read-only” to “not be read-only”
* add a final dot

In the last paragraph :
* remove the second “also”
* before “for automatic testing”, add “for development, “

]]> By: KL http://blog.xebia.com/2010/07/21/lean-architecture-principle-9-comprehensible-over-comprehensiveness/#comment-95732 KL Wed, 28 Jul 2010 13:39:47 +0000 http://blog.xebia.com/?p=5020#comment-95732 I agree with the other comments. A specification perfectly precise is just code, although it is might be more graphical than textual in nature ... (BTW, I agree that code generation should be really efficient). And the target audience of code is the developpers themselves, not the analysts or managers... Documentation relevant to analysts should be in a language they understand fully. I would advise to use the Ubiquitous language for that (yes, I have DDD influence !). But I got bitten also by the separation between business documentation and the corresponding code, that leads to maintenance problems as we all know. My long term ideal (I know no tool for that) would be : * hold the business language with the relevant source code files (as comments for example, see the javadoc idea) * generate an analyst view that only includes what is meaningful to them ; that view should be read-only, so any modification would impact the source You could get additional benefits (for free?) , such as versioning of the business documentation alongside the corresponding code. You could also consider adding in the source files also end-user help information (for generating the end-user help), and examples/tests (useful for automatic testing, or generating the testing manual)(test results could also fit in the source itself, next to the example). I agree with the other comments.
A specification perfectly precise is just code, although it is might be more graphical than textual in nature … (BTW, I agree that code generation should be really efficient). And the target audience of code is the developpers themselves, not the analysts or managers…

Documentation relevant to analysts should be in a language they understand fully.
I would advise to use the Ubiquitous language for that (yes, I have DDD influence !).

But I got bitten also by the separation between business documentation and the corresponding code, that leads to maintenance problems as we all know. My long term ideal (I know no tool for that) would be :
* hold the business language with the relevant source code files (as comments for example, see the javadoc idea)
* generate an analyst view that only includes what is meaningful to them ; that view should be read-only, so any modification would impact the source

You could get additional benefits (for free?) , such as versioning of the business documentation alongside the corresponding code.

You could also consider adding in the source files also end-user help information (for generating the end-user help), and examples/tests (useful for automatic testing, or generating the testing manual)(test results could also fit in the source itself, next to the example).

]]> By: Sander http://blog.xebia.com/2010/07/21/lean-architecture-principle-9-comprehensible-over-comprehensiveness/#comment-95703 Sander Mon, 26 Jul 2010 08:42:08 +0000 http://blog.xebia.com/?p=5020#comment-95703 You hit the nail right on the head. As a matter of fact, the company I worked for at the time was specialized in MDA/MDD techniques. Sadly, due to governmental policies, the project had to be tendered. Still it's a clear example of how you should keep in mind who the audience of the documentation/specification is. Communication is all about the right message in the right format! You hit the nail right on the head. As a matter of fact, the company I worked for at the time was specialized in MDA/MDD techniques. Sadly, due to governmental policies, the project had to be tendered. Still it’s a clear example of how you should keep in mind who the audience of the documentation/specification is. Communication is all about the right message in the right format!

]]> By: Gerbrand van Dieijen http://blog.xebia.com/2010/07/21/lean-architecture-principle-9-comprehensible-over-comprehensiveness/#comment-95677 Gerbrand van Dieijen Sat, 24 Jul 2010 11:01:35 +0000 http://blog.xebia.com/?p=5020#comment-95677 If you've created a specification that is so detailed and complete that nothing has to be questioned by software developers you might as well automatically generate software based on that specification. If you’ve created a specification that is so detailed and complete that nothing has to be questioned by software developers you might as well automatically generate software based on that specification.

]]> By: Tweets that mention Lean Architecture Principle #9: Comprehensible over comprehensiveness | Xebia Blog -- Topsy.com http://blog.xebia.com/2010/07/21/lean-architecture-principle-9-comprehensible-over-comprehensiveness/#comment-95640 Tweets that mention Lean Architecture Principle #9: Comprehensible over comprehensiveness | Xebia Blog -- Topsy.com Wed, 21 Jul 2010 20:11:21 +0000 http://blog.xebia.com/?p=5020#comment-95640 [...] This post was mentioned on Twitter by Arnon Rotem-Gal-Oz and Xebia BV, Diego Magalhães. Diego Magalhães said: RT @arnonrgo: Svan Denberg : Lean Architecture Principle #9: Comprehensible over comprehensiveness http://bit.ly/dc2E6S [...] [...] This post was mentioned on Twitter by Arnon Rotem-Gal-Oz and Xebia BV, Diego Magalhães. Diego Magalhães said: RT @arnonrgo: Svan Denberg : Lean Architecture Principle #9: Comprehensible over comprehensiveness http://bit.ly/dc2E6S [...]

]]>