| Line 13: | Line 13: | ||
* Fedora uses <tt><lang>_<loc></tt> with <tt>_<loc></tt> missing when it is not available. | * Fedora uses <tt><lang>_<loc></tt> with <tt>_<loc></tt> missing when it is not available. | ||
* | * Publican uses <tt><lang>-<loc></tt> always | ||
* ISO indicates one should use <tt><lang>-<loc></tt> with <tt>-<loc></tt> missing if it is not relevant | * ISO indicates one should use <tt><lang>-<loc></tt> with <tt>-<loc></tt> missing if it is not relevant | ||
In Fedora 11, the release notes were produced using the | In Fedora 11, the release notes were produced using the Publican convention. However, release notes are displayed with {{Package|yelp}}, which uses an <tt>.omf</tt> file to determine which language to display. <tt>.omf</tt> files are provided for both the Fedora and Publican conventions so that the release notes always display in the correct language. | ||
The Docs Project could decide to simply produce documents following the Fedora standard. This would be simple to do and not involve any other teams. | The Docs Project could decide to simply produce documents following the Fedora standard. This would be simple to do and not involve any other teams. Publican appears to be happy with whatever languages it is handed in the Makefile. | ||
It might make more sense to attempt to move the entire Fedora project to the ISO standard. This would involve many other teams. Changes to | It might make more sense to attempt to move the entire Fedora project to the ISO standard. This would involve many other teams. Changes to Publican would be nice, but not required. | ||
=== How should release notes be displayed === | === How should release notes be displayed === | ||
Revision as of 23:39, 29 April 2009
There are a number of decisions about how the Docs team will deal with F12 that we should be thinking about.
I have much to add to all of these topics, please feel free to expand on any of these, and add additional decisions we should make.
What will release notes look like
There has been some discussion that the release notes are too long. On the one hand, more detailed release notes discourage people from reading them and are more work for translators. On the other, every change is important to somebody.
What will we use for language-loc codes
Fedora, ISO, and 
publican
- Fedora uses <lang>_<loc> with _<loc> missing when it is not available.
- Publican uses <lang>-<loc> always
- ISO indicates one should use <lang>-<loc> with -<loc> missing if it is not relevant
In Fedora 11, the release notes were produced using the Publican convention. However, release notes are displayed with
The Docs Project could decide to simply produce documents following the Fedora standard. This would be simple to do and not involve any other teams. Publican appears to be happy with whatever languages it is handed in the Makefile.
It might make more sense to attempt to move the entire Fedora project to the ISO standard. This would involve many other teams. Changes to Publican would be nice, but not required.
How should release notes be displayed
Currently, release notes and about fedora are displayed using
Currently, there are menu choices for "About Fedora" and "Help". "About Fedoa" opens the about-fedora doc in yelp. "Help" provides a selection which includes about-fedora and fedora-release-notes (along with some Gnome information which seems to change from release to release).
There appear to be no menu choices leading to README, README-burning-isos, README-accessibility and README-live-images.
By default, the Publican produced RPM adds a "Documentation" menu above "Help" and places the document on that menu. The expectation is that the document is in HTML and is viewed with a browser or HTML viewer. Yelp documents are in XML.
Should we convert minor docs to Publican
README, README-burning-isos, README-live-images, homepage and About-Fedora are still produced using fedora-doc-utils. Should they be converted to Publican?
What is the future of homepage
It isn't entirely clear that this is even needed. Apparently, once upon a time in the distant past, an offline user was directed to homepage rather than seeing a network failure error. This is apparently no longer the case (although there doesn't seem to be total agreement on whether it is or is not). There appears to be no other way to end up at this page other than navigating /var/doc/HTML/...
This page may simply be excess baggage, but some may view the Firefox behavior of failing to end up at this page when the user is offline as a bug.
What does release-notes.srpm look like
Publican produces the rpm very differently than the way we used to. For F11, we more or less followed the model of F10 with the single change that the release notes (only one of 6 docs in release-notes.rpm) were built in the srpm. Previously, already built docs were provided.
Currently, the release notes and the supporting readmes are supplied in the RPM in all the languages (currently around 40). These are installed on every system. The Publican model is to have one document in one language per RPM. It had been suggested that we could subpackage the languages, allowing only the installation of the relevant language. While this could save considerable space, especially as the number of languages increases, it is not at all clear that current release engineering practices and tools could support this in actual practice.