Documentation

[maceligueta]

As a consequence of the 1st Kratos Community Meeting we open this independent discussion wich will lead to an online meeting for a smaller group of people, only those who are interested in this specific topic.
The first temptative date for this meeting is 8th March 2021 at 15:00 CET.
The meeting will be about the issues started (but not finished) in the Community Meeting, but it is also open to any new idea related to Documentation. Please post subjects below.

Already open issues:

• How to better organize the wiki
• How to make the tutorials easy to find
• 'read the docs'
• Distintion between 'documentation for users' and 'documentation for developers'

@antonialarese @rolandwuechner @maceligueta

[loumalouomega]

I added some links: #8380

[RiccardoRossi]

@roigcarlo i think you had a proposal alternative to the "read the docs" right?

[roigcarlo]

Yes, I would go for github pages with some tweaks, similar as the one we have with examples but with some extra features.
The result should look similar as Precice

In my opinion this has sever advantages, but mainly I would remark:

• Generation and host is provided by GitHub
• We can build this directly from the wiki in its current status with little to no effort and maintain it from there after
• Adding / editing can be done directly in markdown
• Once there are PR with new features or changes, doc can be demanded in the same PR as everything lives in the same space

I have been playing with our wiki and the template from the project linked above for a couple of days and the result is something like this:
(It is very preliminary, only Home, Overview and Management Structure are working, all other links will give you error)
https://roigcarlo.github.io/KratosWikiAsDocTest.github.io/

[loumalouomega]

The main pro of Jekyll is that is written in markdown, so we can reuse the wiki (in any case this is more like cosmetic, and the important workload continues to be document itself)

[riccardotosi]

What about also adding to the main README.md the comment that details and instructions about how to use an application are provided in the README.md of each application? I refer, for example, to the README.md of the MappingApplication, which in my opinion is very well done and contains all informations a user needs in order to use the application.

[pooyan-dadvand]

To my understanding, the main issue was the difficulty to find documentation and the organization of the documentation rather than its format.

[loumalouomega]

One important documentation could be (once pip packages are available) to store in https://mybinder.org/ some jupyter notebooks with python code examples. This will simplify to learn, as it is an interactive example where the documentation and execution meets.

Here an example: https://mybinder.org/v2/gh/binder-examples/requirements/master

[maceligueta]

The meeting about the Kratos Documentation will take place today, as nobody complained about the temptative date, at

15:00 CET

https://unipd.zoom.us/j/81286277636

Remember that this is a specific meeting only for discussing ideas about the Kratos documentation.

[maceligueta]

Here are some notes on the meeting held yesterday.

The participants explained some the typical problems encountered:

• The wiki has a lot of information but it is not organized and concrete things cannot be found
• Some new users do not know that there is no exe file and that Kratos must be imported from Python
• Some people exploring Kratos do not know if it can be useful to them
• Nobody knows what are the available options for the Json file (keys can be looked at the defaults, but values can't)
• The deep content of Kratos is only known by those who programmed it

Possible solutions exposed:

• Use Jekyll to organize the information. A hierarchical structure can be created, which links to .md files or wiki pages. It can be added to the same Kratos repository and the addition of information could be forced at pull request time.
• When editing the Json, an autocomplete drop-down selector could appear with all the available options (based on a json schema)
• Also, at runtime, if a Json value (not key) is mispelled, a list of available options can be printed on screen

According to the typical problems and solutions presented, the documentation can be classified is the following categories:

• Introduction to Kratos - what is Kratos and how does it work
• Installation - Compilation
• Contents (Physics) - what can the core do and what can each application do
• How to create an example - Format of the input Files
• Tutorials - first steps, how to create an application, etc
• Deep content for developers - what is available in detail for the Core and the Applications (utilities, processes, elements, constitutive laws, ...)

Main conclusions:

• The documentation can be organized in categories and they are more or less clear now
• Jekyll seems a good option
• The documentation process can be enforced bit by bit just like the tests, by blocking the pull requests until the documentation is added

Several volunteers have proposed themselves to research about all the topics mentioned, to bring more details about the actual feasibility of each of them. These and more conclusions may be presented in the next general Kratos Community Meeting

Please edit this post at will.