Documentation Tools

[Mike Ruckman]

On Thu, 30 Jan 2014 16:55:49 -0700
Tim Flink <tflink at redhat.com> wrote:

> 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

I think that makes sense and shouldn't be too difficult to maintain. 

// Mike
-------------- 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/20140131/b38847ba/attachment.sig>