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