On Monday, I was at Berlin for the first day of the Software Architecture Summit. There I took part at the Hitchhiker’s guide to Architecture Documentation workshop. This is the summary of what I learned:
Hitchhiker’s Guide to Architecture Documentation
In order to run it, you should have AsciiDoctor or AsciidocFX. For one of these two you need Ruby, but the installation is quite easy. Pretty much, this is what you get – on the left side you have editable code and on the right side you have WYSIWYG viewer:
And it is not only this – with a few tricks, it can read other adoc files and it can convert them to html, pdf, doc, excel and powerpoint! Indeed, Excel and Powerpoint from an adoc file. E.g., imagine that you have a CSV file and Excel file with two sheets. The CSV file is easy to be imagined and the Excel looks like this:
Sheet 1:
Sheet 2:
With some help of the poi.apache.org library, in AsciidocFX we can easily generate an HTML file containing these two sheets like this:
If you wonder how it is done, here comes the code from the screenshot:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
== Tabellen Demo mit Excel [format="csv", separator=";", options="header"] |=== Name;Description Asciidoctor;Awesome way to write documentation |=== [option="header",format="csv",separator=";"] |=== include::Adressen.csv[] |=== include::excel/Sample.xlsx/Adressen.adoc[] include::excel/Sample.xlsx/Tetris.adoc[] |
That’s all folks! 🙂