Improve user documentation (feedback from students)

[Carltoffel]

I'm currently giving a Fortran lecture with twelve students, and today I introduced modules, fpm dependencies and finally the stdlib.

I didn't tell them much about the stdlib, instead I asked them to try it out by themselves. Most of them directly found the documentation, but they seemed to be a bit underwhelmed by it.

I'm not up-to-date with the progress of stdlib... sorry if I mention duplicate/obvious things.
Problems that occurred:

• missing or incomplete documentation
• not clear enough what public functions a module has (one student tried to use xoshiro256ss). I think it would be best to have a toggle for private functions
• navigating the docu: when searching in the documentation, it's easier to find the source file, which might be .fypp instead of the actual documentation which is a bit scary for students

After the initial frustration and confusion, they found many useful modules, e.g.:

• error_stop and check
• string type
• ascii
• bitsets
• io (npy)
• arange
• optval
• sorting
• stats

I think overall the routines convinced them, but the documentation definitely needs some improvement. That shouldn't be surprising.

[milancurcic]

Indeed. I don't think we have an actual user doc with explanations and examples, only the spec docs. Definitely much needed.

[jvdp1]

Thank you @Carltoffel for the feedback! Really nice that you tried stdlib!

Re: the documentation, @awvwgk set up a project a while ago for generating something like fpm, with tutorials, how-tos's, ....
Here is the generated site, with an example for stats and I/O with npy files.

Would such a website have helped your students? Or would you expect something different?

[milancurcic]

Re: the documentation, @awvwgk set up a project a while ago for generating something like fpm, with tutorials, how-tos's, ....
Here is the generated site, with an example for stats and I/O with npy files.

This is excellent, I either haven't seen it or have completely forgotten about it. I think that would be a great solution to build on.

[jvdp1]

Yes, maybe we should put first our effort in this documentation to attrack users for stdlib.

[awvwgk]

I started this after we made the fpm docs (#599), but as so often, other things came up and I never got far enough that we could transfer it to fortran-lang.

[jalvesz]

Hi, I think this idea is excellent and a must! Good documentation is paramount for making the library really attractive. @awvwgk I just saw your draft for the site, it looks brilliant, is it based on Sphinx?

[awvwgk]

The website is based on sphinx, happy to give it a push to revive it again if there is interest from people to help with finishing the draft.

[jalvesz]

Yes, looking forward to give a hand with this project! Let me know how could I help.

[jvdp1]

@awvwgk what should be done to revive this? I guess that we should first update the section related to fpm, and probably add new contents in the section how to.

[jalvesz]

An "easy" win I think would be to move the specs under this project. At least to try out and see how it renders

[jvdp1]

An "easy" win I think would be to move the specs under this project. At least to try out and see how it renders

The specs as they are currently are not really useful for the users, at least as an introduction.

See this comment for some aims.

The curreny website contains 2 examples (npy and stats) to illustrate how to use stdlib. I think additional examples similar to those should be added.
Specs as they are now can be found in the Reference page (but I agree that it could be easier to find them).

See also here from more details on how to build the different sections (and their aims)

[jalvesz]

Yes, that's why I mentioned that, when I say "move" the specs I also mean to use the occasion and reshape them under the umbrella of this project. And probably make them more appealing and easier to use/discover (?)

[jvdp1]

Great! I misunderstood your previous comment. Sorry for the confusion. Le dim. 14 janv. 2024 à 12:07, jalvesz ***@***.***> a écrit :

…

Yes, that's why I mentioned that, when I say "move" the specs I also mean to use the occasion and reshape them under the umbrella of this project. And probably make them.more appealing and easier to use/discover (?) — Reply to this email directly, view it on GitHub <#697 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AD5RO7BW6UTPGEVVQCVJ56DYOO363AVCNFSM6AAAAAAVNMH4L6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOJQHEYTSNZQG4> . You are receiving this because you commented.Message ID: ***@***.***>