From Fedora Project Wiki

In Fedora 12, we included an "all changes" table. I think that this was an important addition to the release notes, and we need to include it. However, the delivery also needs to be improved. Hence, I am asking for some discussion among the group.

There are a number of issues:

  • Although these tables are produced mechanically, it isn't an entirely clean process and including it in the release notes proper adds maintenance complexity.
  • Yelp seems unable to deal with the size and/or complexity of these tables, so the version of the release notes installed by default did not include them.
  • Applications are poorly organized into groups in the database, so the Publican produced index is vital to making these tables useful, as compared to keeping the table on the wiki (there is a wiki version at http://fedoraproject.org/wiki/Documentation_Beat_changes).
  • Some users have complained that the size of these tables works against printing the release notes.
  • On the other hand, the size of these tables means that many users would prefer to print these table so they can go through them in a more orderly fashion while offline.

So for Fedora 13 I would like to propose a new document, 'Release Notes Changes'. This would be a separate Publican document, produced in all three formats, but only in en-US. The document would contain only the change tables.

By making it a separate document, we achieve a number of objectives:

  • As a separate document, its production could be further automated, perhaps entirely.
  • The installed size of the release notes would go down considerably.
  • The production of the release notes rpm would be simplified.
  • Individuals wishing to print a copy of the release notes would not need to print hundreds of pages of boring tables, nor would the index include literally thousands of entries which to some readers represent nothing more than noise.
  • On the other hand, users wishing to pore though the change tables could print them independently without also dealing with many pages of, to them, useless prose.
  • The amount of duplication on docs.fp.o would be reduced considerably, since these tables are not translated but are repeated for every language.

I would like to see a discussion about this in an upcoming Docs meeting.