On Thu, 16 Jun 2011 10:38:48 -0400
James Laska <jlaska(a)redhat.com> wrote:
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.
I didn't think about doing that. Personally, I would prefer keeping
everything in the same place instead of requiring network access every
time that the docs are built but I agree that the important part is to
be consistent and have better coupling.
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?
Sphinx works mostly with ReStructuredText [1] which allows for
markup that (in my opinion) is much more flexible and powerful than wiki
syntax. I think of it kind of like a simplified LaTeX
without the brutal learning curve. You can see the rST source on most
sphinx generated pages ([2] is an example)
[1]
http://docutils.sourceforge.net/rst.html
[2]
http://doc.pytest.org/en/latest/_sources/index.txt
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.
The funny thing is that I'm pretty much the exact opposite. I'm not a
huge fan of most wiki dialects and I really don't like using mediawiki
unless I have to. I find trac's moin-ish syntax to be one of the more
pleasant wiki dialects to work with and their rendering engine seems
(to me, at least) to be less bone-headed and less prone to break
formatting than most wiki engines. Then again, I think that trac was
the first wiki I spent a lot of time with. You are absolutely correct on
the history tracking part, though.
A lot of this gets down to personal preference. I may not like
mediawiki and my vote would be for other tools but I think it's more
important to be consistent and have well written documentation. The
ability for others to understand and follow our docs supersedes my tool
preferences :)
Tim