Present project on an upcoming conference

[gernotstarke]

let's move on to new horizons: OOPConference 2019 is coming...

[rdmueller]

I like conference driven development!

[gernotstarke]

I propose to have the following until OOP:

[x] Jekyll-based website, generated (at least mostly) from AsciiDoc [] including the architecture documentation as html (similar to the ArchUnit.org site) [] including the developer guide [] including a user guide with examples [x] using diagrams from both PlantUML AND EnterpriseArchitect [x] generating the architecture doc as word document

[rdmueller]

that list is a good starr.bIbwould also like to go through the docToolchainbfeature list and see if it makes sense to add things like changelog, exportJira, Confluence, Excel, exportMarkdown etc.

[rdmueller]

agreed. I just wanted to do the quick check from the other side of the fence... I guess this list will evolve a bit with our preparations...

[ghp-dev]

Hi folks, I'm looking for the "import excel data as tables into asciidoc" features. From (usually well informed) sources I heard, this might be possible. Only info I found on this repo leads eventually to a 404:

https://github.com/aim42/htmlSanityCheck/blob/9b1bb6be5b41bb6ad14c4a8299200e0c9a3cccdd/src/docs/excel/Requirements.xlsx/General.adoc

[rdmueller]

it is part of docToolchain and the task is called exportExcel (from the view of Excel, it is an Export 😉)

https://doctoolchain.github.io/docToolchain/#_exportexcel

this repository currently contains a good example.

[ghp-dev]

Thanks, so I just misinterpreted the arrow direction :-)

[rdmueller]

Which arrow? I mainly have this diagram in mind:

https://doctoolchain.github.io/docToolchain/#_overview_of_available_tasks

Most data is first exported from the original tool and then included or referenced from the asciidoc documentation... maybe this thinking leads to misunderstanding...

[ghp-dev]

I think the diagram is absolutely correct.

Here's how my misinterpretation happened:

I just returned from sitting through the second day of Gernot's training. And this quote was ringing through the back of my head

"Focus on interfaces to the external systems and the dataflow" (Scoping / Context diagrams)

I then, while scanning the docs for "creating asciidoc tables from excel files" put my visual focus on this:

I thought to myself: well this can't be "importing excel into asciidoc,because whatever that green box is, it is not included into the asciidoc document. Instead asciidoc pushes something into that box.

I didn't notice the word 'include' that was too far away.

Perhaps, ommitting the arrow head from the connector between the yellow box (your solution...) and the green one would have made me think and eventually discover the word 'include'

But once again: Would I've spent more time on scrutinizing the diagram, I'd interpreted it correctly. I just overlooked the info I was looking for at first glance.

[rdmueller]

Thanx for the detailed feedback - it will help me to create better diagrams!

"Focus on interfaces to the external systems and the dataflow" (Scoping / Context diagrams)

very good advice!

The diagram is already the second iteration. The first one contained the same components and connectors but had nearly no structure and thus was unreadable.

Regardings the arrows and what the connectors mean: (I should add this to the documentation)

You mostly have the choice between dataflow and action (which component invokes which other component and thus is the active one). I decided to use the latter. And as you can see, I also mostly don't show components but documents. I guess this even makes it harder to understand... I wonder if there is a better way to visualize this.

The position of the labels is definitely something which can be done better...

[ascheman]

Are you still interested in a conference submission on HSC and docToolchain, @gernotstarke + @rdmueller. Perhaps we could address this in the next months for the second half of 2024 or 2025?

[gernotstarke]

ok for me. My schedule for 2024 is tight. Options would be WJAX in Munich and IT-Tage in Frankfurt.

Presenting with you guys would be a pleasure for me.

[rdmueller]

Great idea. I can support you with slides etc if needed...