search

fortran-lang / stdlib

Fortran Standard Library
https://stdlib.fortran-lang.org
MIT License
1.09k stars 166 forks source link

Improve user documentation (feedback from students) #697

Open Carltoffel opened 1 year ago

Carltoffel commented 1 year ago

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:

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

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

milancurcic commented 1 year ago

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

jvdp1 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

awvwgk commented 1 year ago

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

jalvesz commented 10 months ago

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 commented 10 months ago

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 commented 10 months ago

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

jvdp1 commented 9 months ago

@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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 https://github.com/fortran-lang/stdlib/issues/697#issuecomment-1890919707, or unsubscribe https://github.com/notifications/unsubscribe-auth/AD5RO7BW6UTPGEVVQCVJ56DYOO363AVCNFSM6AAAAAAVNMH4L6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOJQHEYTSNZQG4 . You are receiving this because you commented.Message ID: @.***>