On Thu, Aug 11, 2016, at 09:34 AM, Brian Exelbierd wrote:
This email is to drive some discussion around $subject. It
follows from
a blog soon to be posted on the Fedora Community blog
(
https://communityblog.fedoraproject.org). The text below is copied
from that blog:
Should we stop publishing the current guides now?
The requirement to keep publishing the current guides feels very
self-imposed. Continuing to publish them is a challenge for the new
tooling as it has to be built to accommodate the past and therefore
slows down the future.
Additionally, publishing the current books spreads our resources very
thinly, if not past the breaking point. It also creates inertia which
prevents the move to topics. Confusion can result from this as well
because contributors don't know what to update (old books or new
topics).
Lastly, there is a growing belief in the larger documentation
community
that no docs is better than old docs. Here this is a direct
reference to
the fact that we don't republish all the docs for every release and we
don't thoroughly review every doc that is published. Versioned
docs are
important, but some old materials is probably going to cause problems
(i.e. references to yum or iptables.)
One proposal was to have a "flag day" where we stop updating
the current
docs and another day (or same day) where we stop the publication. this
would definitely need to be moderated for versions not end of lifed.
Please reply here for discussion.
regards,
bex
In a perfect world this would be the ideal solution for this change, but
it presents serveral issues. The main one is that the transition to this
new format is going to take a long time. For instance, I was told it
took the GNOME project 10 years to complete the same transition.
I don't think that it will take us as long, as much of our documentation
is out of date and unmaintained so it will not be ported over), but it
will still take many release cycles to complete this transition. During
that time we are still expected to release some documentation such as
the Installation Guide and the Release Notes.
While the Release Notes are completely redone each release and as such
can be done in asciidoc for the first release after the new site is
ready, the Installation Guide is a big topic and will take time to
properly break down into the new topical format. Using the "flag day"
method or "drawing a line in the sand" would mean we would not be
publishing the Installation Guide or it would be published in a very
incomplete state. Neither option is very good in my opinion.
For this reason I think we need to define a list of documents that still
need to be maintained during the transition (I don't think it will be a
long list) and continue to update only that set of documents, while we
start the process of converting everything.
This will mean that the new docs site will be light on content for a
time, but the content that we will be providing is vital important.