Documentation structure

[KnutAM]

A few thoughts for the documentation that could be good to discuss to avoid major restructuring later?

Documentation of new materials

Currently, we seem to document both the creation of the AbstractMaterial type as well as the material_response function for that material. Would it be an idea to have a single documentation for the material_response function (similar to get_cache and initial_material_state), and only document each AbstractMaterial?

Documentation of internal functions

In my PR #28, I have a utility_functions.jl file with some general purpose functions. These are not exported, but perhaps it would be nice to document these functions in the docs - perhaps under "Internal utilities"? Here we could also document the nonlinear_solver.jl contents?

[fredrikekre]

Might be nice to checkout https://diataxis.fr/

[KnutAM]

I think Daniele Procida makes many good points!
@fredrikekre do you know any equivalent small (julia) package documentation explicitly structured this way? I browsed the list but found mostly larger packages (e.g. some discussion JuliaLang/julia - but seems like Tutorial and HowTo are not included)
I'm trying to figure out how the Tutorial and HowTo should be differentiated.

[fredrikekre]

do you know any equivalent small (julia) package documentation explicitly structured this way?

No, I am only aware of https://juliacomputing.github.io/DataSets.jl/dev/ (doesn't have how-to).

I'm trying to figure out how the Tutorial and HowTo should be differentiated.

Yea, thats my main difficulty too. My current understanding is that tutorials should "teach" but howto should "describe" (e.g. from https://diataxis.fr/introduction/#characteristics-of-documentation). But I agree that it is not very clearcut.

Anyway, maybe it doesn't make sense to structure the docs for this package like that. This was just something I recently look into more closely.

Although, if one would use that system I suppose that (i) tutorials would be very introductory step-by-step guides that is easy to follow along, (ii) how-to would be similar(?) but perhaps for more specific tasks (e.g. how to integrate with Ferrite, how to implement your own model etc), and (iii) reference would basically be the docstrings.

[fredrikekre]

do you know any equivalent small (julia) package documentation explicitly structured this way?

Ha, just stumbled upon https://juliaactors.github.io/Actors.jl/dev/ minutes after my last reply

[KnutAM]

Nice!
The Actors.jl package is really clear-cut following that framework and certainly makes the documentation easy to get into!
It would be really nice to write a doc like that for a package - great input Fredrik!
But for this package, unfortunately I think I opened this issue prematurely for not being a core developer and I will close it to avoid having too many seemingly unsolved issues.