Re: [atomic-devel] Doc format?

[Colin Walters <walters verbum org>]

On Fri, Mar 4, 2016, at 06:59 PM, Josh Berkus wrote:

> One of the reasons I'm asking is that if most things are markdown, we 
> can consider using ReadTheDocs.  But if we've got a lot of ASCIIDocs, we 
> can't.

I'd say there is two levels here: Global docs and per-project docs.  We
should cross link with both.

Some consensus seems to be around asciidoc for global docs, so we'd have:

docs.projectatomic.io as Asciidoc

In particular make these *consumer* (administrator/developer-as-user) focused docs.

As an example, I'd like to have a "mirroring content" section that would cross several
components (RPM, Docker, OSTree).

But that then can call out into e.g. the atomic-reactor or rpm-ostree docs on readthedocs
for some details.  Or if a project chooses to use Asciidoc internally, we can host those
docs too on docs.projectatomic.io/projectname as a readthedocs.org equivalent, or
just concatenate the project docs as a section in the global docs?