AutoQA Documentation

[Tim Flink]

This came up in the comments around #314 but I'm of the opinion that
autoqa-devel is a better place for this conversation.

How do we want to be doing documentation? At the moment, we're kind of
spread across the fp.o wiki and the fedorahosted trac wiki and I agree
with Kamil that we should probably start giving some thought to how our
documentation is organized.

Personally, I'm of the opinion that the fp.o wiki is not the best place
for most of our documentation. Some of it, yes (project overview,
some test documentation maybe) but not most of it. I'm looking at bodhi
[1] as an example where most of their docs are not in the fp.o wiki.

Taking this one step farther, my ideal preference would be to keep the
docs with the code so that the lions share of our docs are in git and
generated at build time (updated on push to master once we get CI
implemented). I think that py.test [2] is a great example of doing this
and I find their documentation well written and easy to follow (created
with sphinx [3]). Granted, the tool is only part of that but I think
that having things in one place and not handicapping ourselves with
wiki syntax and "tools" (finding and changing occurrences are
easier) would be a decent start towards better docs.

Thoughts? Anything I missed?

Tim

PS I'm not proposing we change anything immediately, just thoughts for
going forward

[1] https://fedorahosted.org/bodhi/
[2] http://doc.pytest.org/en/latest/
[3] http://sphinx.pocoo.org/