Thanks for starting this conversation! Some thoughts below ...
On Thu, 2011-06-16 at 08:27 -0600, Tim Flink wrote:
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
I like having the docs more tightly coupled with the code. I've seen
several approaches that work well as long as they're consistently used.
One approach, as you suggest, where the docs live in the code and are
pushed out to a presentation layer. Another, where the docs live on the
wiki, and are pulled down with the code during packaging (anaconda).
Certainly a personal preference, they both work just so long as things
are consistent.
If the docs live with the code, what formats are acceptable? Do the
docs have to be plain/text at that point, or can they include mark-up?
When it comes to mark-up, I do like fp.o/wiki mediawiki syntax *much*
better than TRAC wiki. TRAC wiki syntax is rough (imo) and the history
tracking doesn't seem very robust. I've just spent more time doing
fp.o/wiki work so I'm clearly more comfortable with that approach. I'm
certainly willing to try something different, but editing in TRAC makes
me cringe.
Thanks,
James