ArchUnit needs better (user) documentation

[gernotstarke]

when compared to jQAssist, ArchUnit has some way to go wrt user documentation and accessibility.

Simple proposal: setup a static site generator (e.g. jekyll): You might copy the configuration/setup from arc42.org and simply replace the content...
(there's already a dockerized version so you don't need to install jekyll, ruby etc.).

In case of questions with this setup, I'm happy to support...

[codecholeric]

Puh, for a moment I thought you meant 'architecture documentation' (about which I've already had a bad conscience for a while 😉)

But yes, you're right, the user documentation isn't very good, and the README.md is already getting to its limits. I've kind of procrastinated this for a while, but I guess, I'll take your push and start working on this issue.

To be honest, I have hardly any experience with Jekyll and Github Pages, but I've looked into it, and took your advice, to steal some basics (like using the "Minimal Mistakes" theme) from arc42.org. I've pushed a basic frame together with a docker-compose config (thanks for the tip, when I quickly tried Jekyll a while ago, I was kind of shocked about all the stuff I had to install). See https://github.com/TNG/ArchUnit/tree/gh-pages. I'll try to migrate things from the README.md and fill in more content over the next weeks. Once it's ready, I'll forward www.archunit.org to it.

I'd be grateful for any advice about my setup (as I said, new area for me, and the Jekyll config is kind of overwhelming at the beginning).

Also, if you have any pointers about things I should include in the docs, I'd be happy to hear them, as well. For me it's sometimes hard to imagine where the real problems in getting started are. I've tried to include everything to get going in the README.md, but I've realized, that I forgot many things (like how to configure importing main vs test, etc.)

But I should also start to write a real manual in Asciidoc, I think.

Anyway, thanks a lot for bringing this up and offering support!! Highly appreciated 😃

[gernotstarke]

another (maybe even better) source for re-using doc is the Venom-Story...

Did the docker-stuff (from arc42.org-site) work for you?

[gernotstarke]

btw, for github-pages, you don't need an orphaned branch any longer... you can configure github to publish your pages from any subdirectory...

[codecholeric]

Yes I saw, that I could put it all into docs for example, but I was wondering, if it's better to keep stuff bound to a special tool like Jekyll on a separate branch and only keep the Asciidoc for an user manual in master:/docs. But probably it would be an easier setup, if I just put it together on master, and configure Jekyll / Gradle, to handle the adocs correctly.

For Docker, I found that there meanwhile already is a complete jekyll/jekyll image, so it was pretty easy, I just added the Docker Compose file from https://github.com/jekyll/docker. I still have to do some tests, to see if following the README.md really leads to a working website from a clean checkout.

[gernotstarke]

imho it’s better to build a specific docker image, as you will need specific jekyll plugins/ruby gems… but if the standard image works with minimal-mistakes… that might be a way to go. how large is your jekyll image? (mine is approx 300M including ruby, python + all required gems/plugins)

…

Am 29.09.2017 um 09:03 schrieb Peter Gafert ***@***.*** ***@***.***>>: Yes I saw, that I could put it all into docs for example, but I was wondering, if it's better to keep stuff bound to a special tool like Jekyll on a separate branch and only keep the Asciidoc for an user manual in master:/docs. But probably it would be an easier setup, if I just put it together on master, and configure Jekyll / Gradle, to handle the adocs correctly. For Docker, I found that there meanwhile already is a complete jekyll/jekyll image, so it was pretty easy, I just added the Docker Compose file from https://github.com/jekyll/docker <https://github.com/jekyll/docker>. I still have to do some tests, to see if following the README.md really leads to a working website from a clean checkout. —

[gernotstarke]

too bad I've no experience with asciidoc + jekyll... there are options, though:

https://rgra.github.io/, which is based upon https://github.com/asciidoctor/jekyll-asciidoc

[gernotstarke]

aarg: the standard jekyll/docker setup currently builds with:

Creating archunit_site_1 ...
Creating archunit_site_1 ... done
Attaching to archunit_site_1
site_1  | Bundler can't satisfy your Gemfile's dependencies.
site_1  | Install missing gems with `bundle install`.

and then starts installing... (into the running container, thus potentially loosing the installed gems)

I'd prefer to install this into the docker container just once...

the startup time of the standard jekyll is (on my Mac) approx 30secs,
startup of my (customized) jekyll 3-5 secs...

[codecholeric]

Yes, you're right, would save a lot of building time, to preinstall the gems. So my next steps will be to
a) integrate gh-pages into master:/docs
b) prepare a customized docker image that has the gems installed already

[gernotstarke]

if you do step a), I can care about b) afterwards...

(another advantage: you can manage multiple jekyll sites on your machine, with different themes and gem configurations...)

[codecholeric]

Okay, the site now resides in master:/docs
I created a custom docker image archunit/jekyll, that has the dependencies preinstalled, I'm sure it would be possible to shave off a couple MBs by not extending the official one (or maybe using jekyll/minimal)...
If you do a clean checkout and docker-compose run --rm --service-ports site, does the local server work without pulling any additional dependencies?

[codecholeric]

FYI @gernotstarke : We tried the approach with jekyll-asciidoc and it worked really neat... locally... ☹️
Seems like Github Pages doesn't whitelist the Gem: https://yermilov.github.io/blog/2017/02/20/using-jekyll-asciidoctor-and-github-pages-for-static-site-creation/
So I guess for now we'll create the HTML and check it in, hoping that in the future this will be a more painless process...

[gernotstarke]

I created a PR to show a (draft) combination of diagram and source:

[codecholeric]

I've regenerated the html, looks good 😃
Only that now you need to have 'dot' installed, or the gradle asciidoctor will fail, but I don't think that's a problem, since only a very limited number of people ever generate the user guide 😉
I think this will be a valuable illustration of intention <-> code mapping...

[gernotstarke]

well done, Peter!