A user's perspective on the RTD documentation

[gilrrei]

As a pure user of 4C I find that the RTD documentation brings a huge benefit in terms of usability! It is quite obvious that a lot of work went into it!

However, some stuff might be outdated or hard to understand. So here I present my fully biased view.

Note: the points are built upon personal preferences; this doesn't mean they would make the documentation better/perfect for everybody.

Analysis guide

• I didn't understand what this meant until I looked into the contents. What about the User Guide, which contrasts well with the Developer Guide?
• I couldn't find any information on the input file
  • Type (.dat that it is a custom format and the idea behind it)
  • Content (input file is divided into sections)
  • Required sections (problem type, geometry, etc)
  • YAML/JSON is also possible, mention of schemas? (sorry for the shameless plug)
• Workflow/preprocessing: what about adding satellite projects like lnmmeshio/meshpy etc (also these projects are not listed on the website)?
• Spatial discretization instead of Geometry discretization?
• Elements are not within the geometry discretization
• Boundary conditions etc are outdated with E <num> - blabla and DVOL 5. I think this is something that should be automated using 4C_metadata.yaml
• I don't fully understand the layout of the rtd. Why not add the input parameter reference within the Analysis guide?
• The Analysis guide seems to explain the abstract ideas of the sections, sometimes showing their parameterization, but, in other cases, don't.
• What about creating this part of RTD such that it is divided into the 4C sections, highlighting the idea for the sections, and then listing the available options? I think this would be a bit more intuitive
• The solver section is nice!

Developer guide

• The setup guide is nice
• Kudos for the detailed IDE setup!
• An idea I discussed with @c-p-schmidt: I like the helper scripts to install the external dependencies! Would it be possible to create a bash script that goes through all of them and executes them? Maybe by supported OS ubuntu:20.04 etc? Following the steps of the dockerfile worked like a charm! So why not extract the steps from there?
• What if I can't use any of the presets? I saw that the information came later.
• Coding Guidelines. I saw that there is a section on naming convention, nice! Maybe also something like this for the inputs/input files?
• The information for the Petra object is nice and detailed, but it seems so detached. Why not move it to additional information?
• Something is off in the Additional information page with the directory; the code blogs are the height of the description
• There is lots of really detailed information in the developer guide, which is quite nice!

Input Parameter Reference

• I don't understand the 'Extended Backus–Naur formalism'
• I think this is my favorite section
• It's a bit inconsistent between sections, but it's a really nice feature to have! This increases usability quite a lot!

Tools and Scripts

• nice, but hard to maintain. Why not create a section per tool with a simple short description and link the repos? Less stuff to maintain. Also lnmmeshio, meshpy etc

Appendix

• Writing documentation is nice but why not link to an external but maintained explanation?
• The math guide is nice, but I don't fully understand how this is connected to 4C
• Index is empty
• Reference has some headings called ~

Misc

• Missing installation page. The installation process is a bit hidden within the Developer guide. Maybe add this before the tutorials?
• Lack of descriptions on the different overview pages (e.g., Developer Guide, the first thing you get is the TOC, without information on the content)
• The nice docker feature 4C is available pre-built in a docker image #125 is not in there, which is a shame; it works super well (at least on my OS: ubuntu 20.04)
• Missing links to website, oxygen, and repo
• There is a lot of nice information in here but this increases maintenance as it will get outdated at some point. As an example stuff like how to create documentation. Strictly speaking, it is not part of 4C, so why not simply add a short description and link to an external tutorial
• In coding, we want to reuse code, and I think in the documentation, we should reuse information. Redundant and copied information will sooner or later diverge.

As always, I'm not trying to bash the current state; quite the opposite. A lot of stuff is nice already!

[amgebauer]

Mentioning @ischeider

[ischeider]

@gilrrei Thank you so much for a very good and already quite comprehensive overview on many flaws the documentation has. Some of these are also in my mind, particularly the new features of the input files (yaml, includes, etc.), which are indeed not mentioned so far and may even help to improve the documentation in other aspects, too.

The modifications which are necessary are kind of overwhelming, but I will try my best (and hope for some assistance by others who are interested in a more complete doc as well).

[sebproell]

I can take over the input part soon-ish when yaml is ready and we deprecate dat (#263). There is no need to explain our legacy format if we have a better one.

[ischeider]

I must admit that opposite to @gilrrei 's opinion, the solver section is quite outdated in parts. The use of xml Files for solver settings are not mentioned at all, and the list of preconditioners is not correct, there's the ML preconditioner mentioned, which is not available anymore, and MueLu is mentioned as a future prospect.

I can update the preconditioner section, but I am not able to give comprehensive explanations.