2025 Documentathon: What are your pain points?

[ax3l]

Hi everyone,

We will hold a 3-day hackathon on documentation of WarpX in the coming months.

We already have a list of topics we will work on, but we would like to know from you: what is working, what is not working, and what are you struggling with in the WarpX documentation?

Please comment here :)

[archermarx]

Excellent idea. For me, the distributions and particle injection types have been difficult to get my head around, and I often have to go spelunking into the tests to see how they're used. One that's particularly complicated is the UniformFluxDistribution, which I always have to relearn. I think it would be great to include some equations or examples here to concretize a bit what the different settings do.

[jacoberuppakkattu]

Documentation regarding the uploading of multiple .stl files into the framework and its handling would be useful.

[WeiqunZhang]

Do the objects in the multiple stl files overlap? We could try to add support for that in the stl reader.

[n01r]

@jacoberuppakkattu Please have a look at #6372 and let us know if that helps. 🙂
Making an STL file watertight can still be finicky, especially for complex objects. There may be other file types and readers that could be better suited down the line.

[DanRRRR]

Though it is very very nice that the developers really care about the feedback (and some like Apple for example even pay to those who find the security hole in their software) , but it would be even greater if they add a video or two on Youtube of this sort like "Getting Started with WarpX in 30 minutes or less " where authors show step by step couple most common ways how to install WarpX on

1. your just freshly installed Linux PC starting with the installation of compilers
2. on supercomputer
3. and then how to run couple demo programs in 2D, 3D, RZ and finally
4. how to get raw PIC data and how visualize the results.

As a bonus :

5. make a video with the same on GPU

That would be better than improving any documentation.

Remember "real programmers do not RTFM" ? :)

Great example is "Quick Start" of EPOCH PIC code. Takes 17-20 minutes from empty computer to first run. This was made after users critics that their documentation became totally incomprehensible because reached the size 10 times larger than the gross-book "War and Peace" of Leo Tolstoy