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.