search

jacg / nain4

An API that makes it easier to write Geant4 application code.
https://jacg.github.io/nain4/
3 stars 3 forks source link

Broken page in docs #187

Open jacg opened 3 months ago

jacg commented 3 months ago

Something is amiss here.

Most obviously, the box after

With this, our setup is ready, and we can start the simulation with

is completely empty.

Also, there is a box containing nothing besides

// Important! physics list has to be set before the generator!

where it doesn't make sense.

It seems that the positioning of the anchors in the source code got mangled at some stage.

gonzaponte commented 2 weeks ago

We've probably already had this conversation, but I don't remember the conclusion. I think there is a conflict here. Originally, this document was written to showcase the minimal n4 app, but for that, we used a template that quickly grew to be a more complete example. The idea was that anyone could start a project with this template and have a fair amount of the functionality already exposed. Before fixing this, I would like to discuss which approach to follow:

  1. Create a really minimal app/template and focus this page on that (simpler) version. Then, add other pages documenting expansions to that minimal version.
  2. Rewrite the page to account for this more complete example.

I believe we want to have both: a how-to explaining a somewhat complete example in detail, at the expense of feeling heavier on the reader; and a guide that builds something complex from scratch. Currently, this page is classified as a how-to, so it should be the former, but then it's not really a minimal app, is it?

I can't promise any quick progress, but I might have a few hours to spare in the coming months that I could dedicate to this project.

jacg commented 2 weeks ago

I think we went back and forth on this. The fundamental problem is lack of manpower. We want all of

But all these for-human-consumption code+docs combinations require a lot of effort to make as legible and helpful as possible and cannot really be tested automatically.

We were under huge time pressure when we wrote the app+docs, which explains the confusion in the role they play. Given that we have approximately zero manpower on this project at present, there is not much we can do to fix it.

TLDR: yes we want both, but you can't have everything you want, especially if you don't have resources. So, do what you feel is realistically achievable in whatever time you can devote to this.

Not very helpful. Sorry.