Documentation Tools

[Tim Flink]

On Tue, 28 Jan 2014 09:09:56 -0700
Mike Ruckman <roshi at fedoraproject.org> wrote:

> I've posted a comparison between Sphinx and Dexy [1] - as well as
> updated the phabricator ticket [2]. The tools are pretty similar in
> what they can produce, so it really comes down to what people are
> comfortable with. The learning curve for Dexy isn't steep, and I think
> it's just enough easier to use compared to Sphinx for our purposes.
> 
> I wasn't able to find air-tight reasoning for one over the other for
> qa-devel work - but found dexy a bit easier to use and template.
> Source for both tutorials can be found on my bitbucket profile [3].

As mike started the evaluation, the goal was to see which of the two
tools would be better for qa-devel (and possibly qa) as a whole and end
up with one documentation tool.

As I'm looking through the demo that he came up, adding in my own
experience and what nick said about rtd.org, I'm wondering if we really
need or want to have a single tool.

As I see it, both sphinx and dexy have their advantages and
disadvantages. Sphinx is probably better for documenting a software
project and dexy is probably better for more general documentation.

The main general advantage I see to dexy is that it makes theming and
customization of output much less painful when we want to make stuff
look more fedora-y. However, one of my goals for taskotron is not to
restrict it to Fedora and thus, fedora branding for taskotron-specific
docs is a bit of an anti-goal.

I have two reasons for wanting to keep taskotron as distro-neutral as
reasonably possible:

1. One thing that Kamil said about a year ago now is that there are
   several interesting automation platforms out there but it's a shame
   that they're all really purpose-specific. I agree and see no reason
   to limit taskotron to Fedora from the start - if we can sanely make
   at least the core bits generic, that'll only increase the possible
   user/contributor base going forward.

2. For me, one of the overarching lessons from autoqa is that tight
   coupling leads to pain, lots of pain. AutoQA doesn't really work
   well for anything but Fedora or outside the production
   infrastructure. While not directly related, I do see a correlation
   between keeping the core bits distro agnostic and not repeating some
   of the problematic parts of autoqa - it forces us to decouple some
   things and isolate the Fedora specific bits.

With this in mind, I propose that we use sphinx and rtd.org for
taskotron and self-hosted dexy for the less structured qadevel landing
page which points to various docs and resources.

Thoughts?

Tim
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://lists.fedoraproject.org/pipermail/qa-devel/attachments/20140130/8500ece1/attachment.sig>