DRY docs

[pablobm]

As part of #6424, new documentation was added that duplicated the existing one, which in turn had substantial duplication already.

I propose that we DRY up the existing docs a little bit, splitting it as follows:

CONTRIBUTING.md
README.md
SECURITY.md
doc
├── CONFIGURE.md
├── DEVCONTAINER.md
├── DOCKER.md
├── FAQ.md
├── INSTALL.md
└── MANUAL_INSTALL.md

Details:

• I'm leaving in the root dir the files that I think are standard to find there, at least in the sense that GitHub picks up on them.
• From CONTRIBUTING.md we link to INSTALL.md, which in turn gives options to the reader to continue with either DOCKER.md, DEVCONTAINER.md, or MANUAL_INSTALL.md. We could also separate the rbenv stuff into its own file.
• Regardless of the chosen option, the user is sent to CONFIGURE.md after the install. All this stuff is common to all methods.

[waldyrious]

I normally interpret "install" as something an end-user would do to have a software ready to use in their system. These INSTALL*.md files feel more about something I'd call DEV_SETUP*.md or similar. But I didn't read the contents exhaustively, so I might be missing something.

[pnorman]

I normally interpret "install" as something an end-user would do to have a software ready to use in their system.

In the context of this codebase an end-user is someone visiting the site. They don't have to install anything and should never need to look at the files in git.

INSTALL.md is targeted at people using the code, rather than end-users who interact with the result of the code (the website).

Most of the users of the code will be developers running it locally or non-OSM sites running a variant of the code in production.

[pablobm]

Re: INSTALL.md, I think in this case it doesn't matter too much, as it's out of sight in the docs/ folder, as opposed to in the root dir (where it is in master at the moment).

Note that (at least in my understanding) the docs/ folder is still special. GitHub takes it into account when generating autolinks that appear in the interface (as it happens with the license, etc). However I believe that INSTALL.md is not one such "conventional" file, so GitHub won't do anything special about it.

Having said that, perhaps there's a better, more conventional name that can be used. I'm not sure where to find the full list. The closest I've found is https://github.com/danpoynor/special-github-files, but it's unofficial.

[pnorman]

Having said that, perhaps there's a better, more conventional name that can be used

INSTALL.md comes from the long-standing GNU standards and is what is commonly used. As far as I know it has no special significance to Github.

[pablobm]

I have now rebased (actually redone from scratch) this PR, after the merge of #6424. It's ready to be reviewed.

[tomhughes]

The link here is broken because CONFIGURE.md is still in the top level - the same applies to the What's next? section in the other files as well.

[pablobm]

I think you mean CONTRIBUTING.md? I have fixed all instances now, thank you!

[pablobm]

Apologies for the merge commit. After some head scratching wondering where that had come from, I realised that I had clicked a button that GitHub makes all too easy to click by mistake. It's fixed now.