Tutorial / Learn page

[milancurcic]

What should the learning page and tutorial look like?

What should they cover?

How should they be organized?

Let's discuss.

Follow up from fortran-lang/fortran-lang.org#5 .

[certik]

I like how Rust does it: https://www.rust-lang.org/learn

They have "books" on various subjects. So one book can be a general tutorial to Fortran, like at fortran-lang/fortran-lang.org#5.

Another book can be the "Best Practices" from here:

https://www.fortran90.org/src/best-practices.html

where I collected some of the common idioms and how they should be done in the modern way.

Another book can be Python Fortran Rosetta Stone:

https://www.fortran90.org/src/rosetta.html

Another can be FAQ:

https://www.fortran90.org/src/faq.html

...

[LKedward]

I agree, the Rust learn page is a very good example.
I like the idea of having short online 'Books' for different topics.
We can easily add books as they are written and group them on the top-level Learn page by category.

A possible structure:

• Category: Getting started

  • Book: Quickstart tutorial (existing tutorial)
  • Book: Fortran FAQ (fortran90.org)
  • Book: Fortran for Python programmers (fortran90.org)
  • Book: Fortran for C/C++ programmers (see flang)
  • Book: Fortran best practices (fortran90.org)
  • Book: Fortran community style guide

• Category: Core Language Documentation

  • Book: Basic programming concepts (types, variables, constants, arrays, operators, expressions, character strings)
  • Book: Program units (scoping units, programs, procedures, modules, submodules) and control flow (conditional and looping constructs)
  • Book: Working with arrays (static, automatic, allocatable, pointer, passing/returning arrays to/from procedures)
  • Book: Data input & output

• Category Advanced Language Documentation

  • Book: Object-oriented Fortran
  • Book: Submodules
  • Book: C interoperability

This makes it easy for people of different abilities to quickly find relevant documentation.
Getting the structure perfect first time isn't important since we can adjust as content is added.

The core and advanced documentation should eventually cover the whole language in detail as a searchable and more accessible (easier-to-read) alternative to the standards documents.

Finally there should be a section at the bottom of the learn page with links to external resources: books, standards documents, mailing lists, fortranwiki etc.

What do you think?

[certik]

I agree.

…

On Sun, Apr 19, 2020, at 3:34 AM, LKedward wrote: I agree, the Rust learn page is a very good example. I like the idea of having short online 'Books' for different topics. We can easily add books as they are written and group them on the top-level Learn page by category. A possible structure: * Category: Getting started * Book: *Quickstart tutorial* (existing tutorial) * Book: *Fortran FAQ* (fortran90.org) * Book: *Fortran for Python programmers* (fortran90.org) * Book: *Fortran for C/C++ programmers* (see flang) * Book: *Fortran best practices* (fortran90.org) * Book: *Fortran community style guide* * Category: Core Language Documentation * Book: *Basic programming concepts* (types, variables, constants, arrays, operators, expressions, character strings) * Book: *Program units* (scoping units, programs, procedures, modules, submodules) and control flow (conditional and looping constructs) * Book: *Working with arrays* (static, automatic, allocatable, pointer, passing/returning arrays to/from procedures) * Book: *Data input & output* * Category Advanced Language Documentation * Book: *Object-oriented Fortran* * Book: *Submodules* * Book: *C interoperability* This makes it easy for people of different abilities to quickly find relevant documentation. Getting the structure perfect first time isn't important since we can adjust as content is added. The core and advanced documentation should eventually cover the whole language *in detail* as a searchable and *more accessible* (easier-to-read) alternative to the standards documents. Finally there should be a section at the bottom of the learn page with links to external resources: books, standards documents, mailing lists, fortranwiki etc. What do you think? — You are receiving this because you commented. Reply to this email directly, view it on GitHub <https://github.com/fortran-lang/fortran-lang.github.io/issues/7#issuecomment-616086708>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAFAWGGDTDM23JYL5PED7TRNLARVANCNFSM4MJ2C3VQ>.

[vansnyder]

I've never used GitHub. I can't find anything. A tutorial how to use GitHub in the Fortran project context would be useful.

[milancurcic]

Hi @vansnyder, I'm happy you joined. I assume you need help finding your way around GitHub and getting used to its interface. There is GitHub Help documentation, but to be honest I don't think it will be helpful. Instead, I recommend just exploring and trying to find your way through practice. It looks quite busy at first but you get used to it.

If you'd like, I'm happy to get on a Zoom video call with you to guide you via shared screen. Just let me know.

Otherwise, the best place for you to start is the J3 Fortran proposals repo:

https://github.com/j3-fortran/fortran_proposals/issues

You will find many discussion topics there, a few of them evolved into J3 papers. I suggest to read those, and post in whichever you want.

---

But your point also makes me think of this: We should probably have a dedicated "Contributor's guide" page on the website that would explain:

• What is where, e.g. proposals, standard library, package manager, website code etc.
• Basic workflow for each project. E.g. workflow for proposals is different from the workflow for stdlib or fpm, which is different from that of the website code;
• A list of items that we need help with the most from new contributors.

This info is basically already in each of the repositories. However, a dedicated single-page guide for all fortran-lang projects on the website would be helpful for people who aren't already proficient with GitHub. We want everybody who is willing to be able to join and participate.

How do we further lower barrier to entry?

[melissawm]

I'd like to link this issue from stdlib. I think many of the points I raised there are valid here.

I'd also like to offer to write the Contributor's Guide.

[milancurcic]

Like what @arjenmarkus said on the mailing list. the quickstart tutorial needs work and is IMO the highest priority to get into a somewhat polished and complete state.

I will open a dedicated issue for that later today so we can discuss the contents and style.

[milancurcic]

@melissawm Great, a contributor's guide is direly needed if we are to attract new contributors.

Are you thinking of a contributor's guide specifically for this repo, or for fortran-lang projects as a whole?

Each project should have its own contributor's guide. This repo has this. Can you please take a look at it and think of how it could be improved?

Further, what do you think about having an overall contributor's guide which would be a page on the website, basically a guide to contributing to the community project as a whole, and then linking to individual project contributor guides?