Markdown and wiki pages for ACE / IIB / WMB projects
When we do a SonarQube analysis for ACE/IIB/WMB code, we end up analyzing all the code ESQL and msgflow code (maps, esql, subflows, msgflows)
We build a lot of information around relationships between queues, flows, http connections, file interactions and the ESQL code itself.
We merge all this information together, and when we complete the Sonarqube analysis, we also generate a set of web pages and diagrams that document your system as we understand it.
What this means is that you an automatically generated summary of your project which you can use to understand your system better.
Whether it's
My last few posts have been around making use of GitHub (and GitLab) Ci/Cd tooling.
Both GitHub and GitLab provide a basic wiki that teams can use to help document and understand their projects.
It is based on creating markdown pages. One thing that most IT people know, is that developers don't generally like creating documentation, and it often becomes stale quickly.
If it's stale, then it not very useful, or worse it could give someone the wrong understanding.
Of course having incorrect documentation can still be useful if the author is still available to ask about it. It can be a good start of understanding how things work.
This sort of reluctance around creating documentation is why we went with generating web pages and diagrams, so that they stay current. "The truth is in the code".
We also know that documentation that is closer to the code is better - the readme for a project inside the source code is more likely to updated then a Confluence or SharePoint page in a separate system.
From a security perspective, those who built the system are more likely to be the ones that should have access to the documentation, so having it in the project can make sense from a security perspective - you get access to the code and documentation at the same time.
领英推荐
On the downside, it does create a lot of potential silo's of information that isn't shared or available and isn't indexed or searchable.
So I'm not suggesting you throw away your knowledge sharing tool anytime soon.
Having generated documentation can also help system architects to understand how the system is developing compared to the original architectural decisions. They can see the architecture live, rather then?be looking at PowerPoint or Visio diagrams that the developers ignored years ago.
So for all these reasons, we updated our plugin to take the diagrams and web pages we have been creating and ported them so that they can be added to a projects GitHub wiki.
It's not as interactive as the generated web pages - you can't pan and zoom in the diagrams or sort and filter the tables, but it does allow the viewer to understand the project better then just be looking at the code.
And, if it's included in the build process (using a GitHub workflow to checkout the wiki, add the pages and commit them back), teams can see the latest documentation right there in GitHub.
I am going to do a quick walkthrough of the GitHub workflow and diagrams that get created.??
Wednesday the 14th - 9:00pm?(Brisbane time):
For more information on this new tool or if you are interested in a demonstration please drop me an email to:
Or contact me via the contact page on our website - www.bettercodingtools.com
Regards
Richard