User-friendly README

[Expander]

Over time, our README.rst has grown to a large file with lots of installation/build instructions for developers. OTOH, the part that contains physics/application-related information is significantly smaller. I think it is time so improve that and clean-up or split the README.rst file.

My first proposal would be to reduce the size of the README.rst file and introduce more links to sub-pages for more details. We may think about the following structure:

1. Quick start (similar to what we currently have)
2. Build instructions (very short or link to separate doc/build.rst file)
3. Usage examples (short script or physics examples or links to sub-pages)
   a) Predefined models
   b) Creating new models
4. References

What is your opinion?

[pathron]

Actually just today I was there wasn’t enough content :) though this is not really disagreeing with you because we can also add some additional documentation in sub pages. For the sake of an honours student project I was looking up how Himalaya is used, but the details are not in the README so I ended up looking at our FS2 manual.

So anyway my vote is short sections with the parts you describe, but with links to other pages. Unfortunately a lot of people will just view the README with less of whatever, so they will miss the links, but not sure there is anything more we can do about that other than clearly state further documentation is in the doc directory.