Add article "Architecture verification and documentation with jQAssistant and arc42" #56
Conversation
There was a problem hiding this comment.
I like it. At the end you are talking about the steep learning curve. I fully agree with that. On suggestion from my side would therefore be to maybe also explain how to execute the rules and how those rules are basically structured and how they work, butI haven't looked into the example project. Maybe this would answer my questions.
| For reporting, we'll use the [jqassistant-asciidoctor-extension](https://github.com/jqassistant-tooling/jqassistant-asciidoctorj-extensions), which is an extension for asciiDoctor parsing the jQAssistant report and providing inculde directives for the results. | ||
| As a documentation template, we’ll employ [arc42](https://arc42.org), a framework for documenting software architectures. It already provides a structure we can hook in and is available as [asciiDoc template](https://arc42.org/download#file-based-formats). | ||
|
|
||
| You'll find the documentation in the `src/docs` directory of our sample project. TThe project is pre-configured with the Asciidoc Maven plugin and the Asciidoc multipage HTML plugin, which creates a beautiful multipage documentation in your `target/docs` folder, when running the project with `mvn verify`. |
|
|
||
| In our sample project you'll find the ADR examples in the folder `src/docs/adr`. | ||
|
|
||
| With the yaml files ingested by jQAssistant we can then write concepts and constraints targeting those nodes. Finally we can include all ADR documentation files in the architecture design desciions document. |
|
Another thing I usually struggling with is how to identify the stereotype e.g. is it an entity, an adapter, a port an infrastructure level component, an application service,... of a class if this is not encode in the package structure. For example it is usual in a DDD approach to structure your application based on the bounded contexts and aggregate roots which means you package name looks similar to lab..<context/aggregate root> and everything, e.g. repository events services,... is included in this package. Packages are cut according to domain aspects not to technical aspects. In this case I need something else to identify the stereotype of a class. Any Idea? |
You are right, the given sample project is quiet simple and represents only one context. This makes it easy to identify the concepts based on the conventions (but this was intentional to keep it simple here :D ) Basically this is about testability of the architecture. We already do it with code : make it small, make it independent, if you cannot write a test for it there's something fishy. Same goes for architecture: if you cannot test your implementation structure easy enough, maybe something should be more visible or also amybe something is not there at all. |
Thanks :) |
There was a problem hiding this comment.
Great article. I noticed a couple of spelling errors, which I have noted in the text.
There's a certain barrier to adoption, which is the very technical syntax of the XML rules file(s). I wonder whether this might be usefully overcome by using Anthony Anjorin's Pedantic extension to MPS - this is a model-building tool par excellence, which may be able to generate the specification language without requiring users to learn its syntax.
Anthony is a member of our Global CDQ practice. His github repo can be found under https://github.com/anthonyanjorin
|
|
||
| ## Showcase: ADR validation | ||
|
|
||
| To show what I mean with "living documentation" and what is possible besides analysing code using jQAssistant, I created a showcase, validating [Architecture Descicion Records (ADR)](https://github.com/joelparkerhenderson/architecture-decision-record). |
There was a problem hiding this comment.
Spelling: Descicion -> Decision
|
|
||
| With everything in place, we are now ready to incorporate the results into the documentation.. | ||
| As you may recall, our objective is to provide a comprehensive overview of all ADRs and their associated constraints. | ||
| o facilitate this, we are introducing a new concept called `adr:constraintReport`. This concept does not modify the graph in any way. Rather we use the query result as a structured report. |
There was a problem hiding this comment.
Missing "T" at start of line
This sound like an interesting approach. I am not really fluent with DSLs and MPS but will have a look into this. |
Thanks for clarifying. I really meant the parts embedded in the XML as CDATA. I would imagine that there's a lot of scope for subtle errors if this is edited directly. Of course, if you're using another tool to develop the Cypher statements this is a different matter (particularly if you can unit-test the query language statements somehow). |
No description provided.