[Bug 427481] Review Request: documentation-devel - Documentation tool chain

[bugzilla at redhat.com]

Please do not reply directly to this email. All additional
comments should be made in the comments box of this bug report.

Summary: Review Request: documentation-devel - Documentation tool chain


https://bugzilla.redhat.com/show_bug.cgi?id=427481





------- Additional Comments From kwade at redhat.com  2008-01-14 11:15 EST -------
(In reply to comment #15)  ... some questions and points.

I look forward to finally being able to see this toolchain, and I'm sure many of
us will review it for use or replacement of existing parts of the Fedora Docs
tools/infrastructure.  Major kudos to Jeff, whose work I've long admired and
benefited from.  This package arrives at a good time for tech review as we
revamp parts of documentation production with the help of Fedora Infrastructure.

My comments here have the caveat that I have not done a full feature review of
the toolchain, so I am plainly curious what it provides that is missing in the
existing toolchain and infrastructure.  Especially, what is provided that the
community has been asking for.  If we can answer these questions here, we can
save others from having to do the deep research themselves. :)

> It is a mature project with a significant existing community of users, who have
> it embedded in their enterprise infrastructure.

Is this community entirely internal to Red Hat?  That may explain why no one had
access to the Fedora collective consciousness about *-devel for namespaces,
which is one of those things no one wrote down because, "Everyone knows it." :)

> The package brings together an end-to-end opensource toolchain that
> allows open source projects to produce professional documentation,
> taking several forms of input and outputting html, pdf, manpages,
> xml, and several other formats.
> 
> It produces branded documentation using templates.
>
> It handles multiple language translations.
>
> It's been developed over a number of years and is used in an enterprise setting.
>
> Basically it provides the whole kit and caboodle for professional open source
> documentation production from source. 

Sounds like the existing Fedora Docs Project toolchain.  It does all those
things.  One difference, it was developed by volunteer contributors working from
the Fedora community, so I reckon it hasn't nearly the same amount of features.
 For example, I'm sure it outputs better PDFs since I know Jeff has done a lot
of work at making passivetex and FOP spin and hum.

> In terms of Fedora it provides a missing
> infrastructure piece for documentation production and translations.
>
> In terms of the wider scene it provides a missing infrastructure
> piece, 

Confused here -- we've an existing toolchain that does all this, all built and
hosted within Fedora over many years.  What is missing?

Fedora Infrastructure hasn't come forward yet and said they are missing any of
these functions.  Nor has anyone else from the Fedora community, with the
exception of prettier/unbroken PDFs.

> think that a canonical name is not out of place. Red Hat / Fedora have a history
> of providing significant plumbing pieces to the community (like NetworkManager).

The exception is, those pieces were developed initially in the open, which is
one way to avoid unfortunate namespace problems.

Ironically, we often point to NetworkManager as a lost marketing opportunity,
since common credit for "first use" went to other distributions.  If this doc
toolchain package is going to so significantly change the landscape for free
documentation, we have missed the chance to publicize its development.  Let's
not miss any further opportunities.

Finally, big +1 to the idea of a content development spin.  Huzzah! Let us know
on fedora-docs-list if you want any community contributors and testing.

-- 
Configure bugmail: https://bugzilla.redhat.com/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.