Writing the fpm book

[awvwgk]

We are progressing quite well with fpm on the feature implementation and I really like the growing developer documentation at https://fpm.fortran-lang.org, but the user documentation is not in such a good shape. Writing user documentation usually helps to find rough edges and might also be useful to explore features we want to have before actually implementing them.

Our only user guide is the packaging page right now. We have been discussing an fpm (mini)book at fortran-lang/fortran-lang.org#156 briefly and it might be worth to have a look into this again.

Since writing a (mini)book on fpm is a huge project, it requires some careful thoughts and coordination first. That's the reason for opening this thread.

[LKedward]

I've been thinking the same thing recently regarding user documentation. The current packaging guide is a great format, but has gotten a little out of date with all the recent progress. +1 for a mini-book for fpm. I'm not sure what the best approach for structuring it is, but I guess a good example would be the Cargo book.

[awvwgk]

I was thinking of doing a couple of case studies.

As an introduction for users new to Fortran and fpm we would describe how to start from scratch, using fpm-new, fpm-build and fpm-run to get an initial project together. How to expand by including dependencies and writing tests (fpm-update and fpm-test). This should cover most of the everyday fpm commands.

Interesting for project maintainers would be an example were we take an existing project and port it by examples from whatever build system it had to fpm, while reproducing and extending the original project. I took a similar approach when writing the make example in fortran-lang/fortran-lang.org#160 using the csv-module.

Finally, I would like to see a guide as well for users coming to an fpm enabled project explaining how interact with it and how to use it (fpm-install), in a manner of showing the least exposure to fpm for getting a project setup. This would also be valuable for packagers trying to get fpm enabled projects in Unix distributions or on conda-forge, but there the focus is slightly different.

[milancurcic]

I agree, +1 for case studies and example-oriented teaching.

[milancurcic]

Would it be helpful to define two kinds of fpm features/functionality?

1. Mostly stable
2. Moving targets

Writing the fpm book to initially cover category 1. would minimize maintenance as fpm develops.

[awvwgk]

At the current pace of fpm development I'm confident enough to plan on using fpm next summer term (April 2021) for teaching Fortran. I'll definitely write a sizable chunk of introduction to fpm for the course, which could be repurposed for the fpm book later.

[awvwgk]

I'll track my progress on this over at our groups public teaching resources: grimme-lab/qc2-teaching#18

[awvwgk]

The first draft of the course material with fpm is online now at https://qc2-teaching.readthedocs.io/en/fpm/, but not completely official yet.

Turned out that writing the installation instructions is the most difficult part, because the students are doing the course on their own machines. Using the fpm download page seemed too difficult for now, because those students will be beginners at programming and even setting up a correct PATH variable can be hard at this stage. I'm still hesitant at this point because there is a lot of things that can go wrong with the additional complication of installing fpm now.

For good measure I setup a homebrew tap as well to account for possible installation issues on OSX. Also, I started my own MinGW packaging for MSYS2. A lot of work for preparing the course with fpm, but I think it is worth the effort.

Feedback is of course welcome, feel free to comment here or on the issue linked above.

[certik]

Thank you everybody for thinking about documentation and for writing it.

I am also very close to use fpm for my older projects, but I first want to write the cmake backend, so that I can check the cmake files into the repository, to make the transition smooth.