On 06/16/2011 08:38 AM, James Laska wrote:
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.
Resurrecting a month old thread in the hopes that we can get some of
this figured out.
Any thoughts on the whole mediawiki vs trac vs sphinx vs epydoc vs
notes-tied-to-carrier-pidgin question?
Tim