WIP: DRY docs

[pablobm]

As part of #6424, I'll have to add documentation that will duplicate the existing one, which in turn has substantial duplication already.

So I was thinking: how about we DRY up the existing docs a little bit first? I'm proposing we split it as follows:

CONTRIBUTING.md
README.md
SECURITY.md
doc
├── CONFIGURE.md
├── DOCKER_INSTALL.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 (I need to double check).
• From CONTRIBUTING.md we link to INSTALL.md, which gives options to the reader to continue with either DOCKER_INSTALL.md or MANUAL_INSTALL.md.
  • A new DEVCONTAINER_INSTALL.md can join in the future, and 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.

Thoughts? Note that this is only a draft, to get your impressions before investing more time.

[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.