My goal is to make the software-world a better place with one doc at a time.
I truely believe that one of the biggest problems of the software-world isn’t technology, skills or quality in the broad sense but missing documentation. Another is missing simplicity.
Regarding the documentation - there are some open source projects out there which do have great user documentation, but as soon as you try to change the code, you are on your own - no documentation of the solution architecture. I only remember one open source project with a proper documentation of the solution architecture (http://biking.michael-simons.eu/docs/index.html), but maybe I don’t know enough OS projects :-)
So my aim is to build software on the works of Gernot Starke and Peter Hruschka to make use of arc42 even easier. In order to achieve this goal, there are the following ressources available:
- the original arc42 pages in german and english (Created by Gernot Starke and Peter Hruschka)
- the arc42 ressources on github
- github.io pages containing the links to all known available arc42 templates in different formats
- the asciidoc2confluence-script to easily publish your docs to confluence
In addition to arc42, my second stream of thoughts is about the documentation of test results. The red/green output of unit tests is often not enough - it doesn’t say what has been tested and also reading the code is not the solution for all stakeholders.
So I first came up with the Grails FilmStrip-Plugin which displays screenshots made with the functional test module of Grails, as a film strip. This way, anybody can easily inspect those screens and check what has been tested.
Together with Tobias Kraft we developed this idea further and merged the test specification created for Spock Tests with the screenshots made with Geb and came up with a good looking test report. As a result, there is
- the execl2spec script on github which let’s you define the spock specification in a spreadsheet. A script will turn the spreadsheet in a Spock test skeleton.
- a full blown example for creating asciidoc based test reports with Geb based screenshots
- we presented the example at Entwicklertag Karlsruhe 2015 (video)and JavaLand 2016 (both talks where held in german)
When it comes to simplicity I often have to think about a talk given by Dierk König with the headline “Einfach” - “Simple”. The “facts” presented in this talk might not have a scientific foundation, but they sum up what many of us experience every day and Edsger Dijkstra fomulated as “Simplicity is a great virtue but it requires hard work to achieve it and education to appreciate it. And to make matters worse: complexity sells better.”
The Blog uses github pages together with Jekyll as engine. Template from Jekyll Now
Contribute
You’ve found a typo? You’ve got a good idea for an article for this blog?
Just for this repository on https://github.com/rdmueller/rdmueller.github.io and send a pull request!