Clarify relationship with upstream projects documentation

[jlebon]

We need to talk about the relationship of these docs with the upstream documentation of the constituent projects. For example, both ostree and rpm-ostree have documentation at Read The Docs. This is completely justified for ostree, which is extensively used outside of Atomic Host. Even for rpm-ostree though, I think it makes sense in keeping our own set of documentation since although it is mostly used in the Atomic Host context, it can be (and is) used outside of that context as well.

So then, we need to figure out what makes sense to have here. For reference type stuff, like the command-line interface, I think the only sustainable path is to have the canonical copy be in the upstream repos. And then put that in a format that can be published both as a man page and at RTD, and then link to those pages from the Atomic Host docs?

Personally, I think even for user guide style documentation (e.g. the whole "Using OSTree" section), we should just keep it all upstream and either publish it twice (once in Read The Docs and once at Atomic Host docs) or just make the Atomic Host docs refer to RTD. There's some details that might seem more out-of-place in one site than in another (e.g. command outputs referring to Fedora Atomic Host), but I think we can live with that. Though I'm interested what others think. Any other sane way to split this without inviting too much duplication?

Keeping it all upstream means that there's a much higher chance that the documentation will be kept up to date as new features are added (there's a lot of room for improvement there, though I think with a clear policy we can move forward and start improving as well as entice folks to contribute!).

[cgwalters]

I think my tentative vote is "publish twice".

[jberkus]

So ....

The idea of having the rpm-ostree reference docs included in the atomic-host-docs was pretty much strictly based on the fact that the documentation at RTD is incomplete, and including rpm-ostree documentation in atomic-host-docs was a way to make sure it got completed.

For that matter, we are likely to include a copy of the atomic CLI reference docs, because while those are complete, they are published only in man page form and not otherwise available on the web.

From my perspective, the idea policy would be:

• Upstream project hosts reference (i.e. each command and switch) documentation
• AHD hosts "how and why to use this to accomplish tasks" docs.

For example, ideally, rpm-ostree RTD would have the "rollback" command under "R", and AHD would have when to rollback and how that looks in a sysadmin workflow.

BUT ... that only works in cases where the upstream docs are complete, on the web, and linkable on a per-reference basis. If they aren't, managing 5-6 separate documentation projects instead of one big one is an unreasonable task, so we'll put them in the AHD.

Make sense?