Consider synchronising some or all of README.md with the first page of the book

[JLouisKaplan-Arm]

I noticed that the book has a section 'How this book is created' and the README.md has the exact same section but under the title 'Why an open source book?'. It might be beneficial to find a way to keep some or all of the README.md synchronised with the book itself.

This could also extend to other sections. For instance, the book has a section placeholder for a contributions guidelines appendix section. This could be synchronised with 'contributing.md'.

In a previous project (https://github.com/JuliaRheology/RHEOS.jl), drift between the README and first page of the documentation became quite a consistent issue so we ended up just programatically pulling README.md (with some minor programatic tweaks) into the documentation build system, which worked quite well.

(as a side note, IMHO I find the title 'Why an open source book?' to be more appropriate for the content within that section.)

[kbeyls]

Thanks for sharing this idea, @JLouisKaplan-Arm !

I'm a bit in doubt whether it will end up saving work or not to try and share a part of the README.md with a part of the introduction of the book. It might; but I also guess it we may end up having legitimate reasons to want to diverge the 2 a bit.
How complex would the infrastructure be to keep both parts in sync?
My feel is that, under the assumption that we won't be making many changes to those parts of the README and the introductory section of the book, my guess is it's overall better not to try to synchronize them automatically. I'm happy to be proven wrong on this though.

I like your proposal to change the title in the book to "Why an open source book?". Would you like to create a pull request to implement that change?

[JLouisKaplan-Arm]

whether it will end up saving work or not

I see what you mean. Definitely hard to tell at this early stage in the book how useful it will be, so it might not be worth the infrastructure overhead right now, especially if divergence is desirable later on as you mentioned.

How complex would the infrastructure be to keep both parts in sync?

Unfortunately I've not worked with pandoc before (project linked above used Julia's Documenter.jl package). I'm aiming to read into it in more detail over the next few weeks. Can report back here if I make any headway.

"Why an open source book?". Would you like to create a pull request to implement that change?

Will do!