Archive:Docs decisions for F12

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.

As these discussions develop, we may catch some of these in Bugzilla. Eric has created a tracking bug we can use for attaching anything we need to deal with for Fedora 12 -- https://bugzilla.redhat.com/show_bug.cgi?id=500474. There is no need to be shy about adding bugs or comments in bugzilla. It is our tool, not a problem to use it.

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.

A proposal I would like to make is as follows:

• Continue to have the beats follow the release notes pretty much as it is now
• For each beat, emphasize one or two really cool new features
• Following that, list each changed package with the old and new versions and a link to the upstream page

That way someone waiting for a particular bugfix can easily determine whether it is there, the release notes are shorter and much more approachable, and a lot less material needs to be translated.

I have added a draft page with this concept. See User:Jjmcd/Drafts/Test_of_table_RNs and compared to the original (Documentation_System_Daemons_Beat) there is more information and less to translate. For the terminally curious, here is a Publican example: http://jjmcd.fedorapeople.org/Download/Example/sect-Release_Notes-System_Daemons.html

--McD

I went looking at some other release notes to see what others are doing. Obviously, release notes for applications are an entirely different animal than release notes for an operating system, so I went to dig around and see what other distros had. What I found was an amazing unevenness. RHEL was (unsurprisingly) the closest to ours, but some were (IMO) incredibly bad. FreeBSD's consisted entirely of single sentence paragraphs stating that this package was changed from version X to version Y. Another one (I can't recall which now, maybe PCLinux) was nothing more than a list of included packages with versions. Ubuntu only highlighted major bugs, as did a few others. Besides being more complete, the major place we were an outlier was in the inclusion of "marketing fluff". At FAD we talked about 2 or 3 documents for different audiences, this would seem to indicate that might not be such a bad idea. --McD

Ensuring good relationship with L10n

Docs work immediately impacts people around the world beyond English-speaking countries. We need to ensure that we are making life as easy as possible for translators, whose work is rigorous, detailed, and constant.

• How can we best eliminate jargon from documentation?
• Review of all docs?

What will we use for language-loc codes

Fedora, ISO, and publican all have different ideas about language-location codes. What will we do?

• Fedora uses <lang>_<loc> with _<loc> missing when it is not available.
  • More specifically, Fedora follows the convention used in glibc or POSIX. I've also seen the @ modifier used to identify a script; for example, sr@Latin (Serbian language written with the Latin alphabet). --Rlandmann 06:50, 7 May 2009 (UTC)
• Publican uses <lang>-<loc> always
  • From version 0.43 onwards, Publican also recognises simply <lang>, and will attempt to infer loc if it is left out. <lang>-<loc> is still better if you want to make sure of what you're getting. --Rlandmann 06:50, 7 May 2009 (UTC)
• ISO indicates one should use <lang>-<loc> with -<loc> missing if it is not relevant
  • AFAIK, this isn't ISO, but IETF. (BCP 47 - Tags for Identifying Languages, based on RFC 4646, in turn based on RFC 3066). Publican aims to comply with this standard. --Rlandmann 06:50, 7 May 2009 (UTC)

In Fedora 11, the release notes were produced using the Publican convention. However, release notes are displayed with yelp, which uses an .omf file to determine which language to display. .omf 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. Publican appears to be happy with whatever languages it is handed in the Makefile.

This is not quite true; Publican draws material from the Docbook XSL stylesheets. Therefore, if you put the French PO files in a folder named french and create a make target called "french", Publican will apply the po files correctly, but since there's no XSL stylesheet for "french" (the stylesheet is called "fr"; in Fedora 10, this is is /usr/share/sgml/docbook/xsl-stylesheets-1.74.0/common/fr.xml), Publican won't be able to find the words for "Chapter" "Index", "Back", "Next", "Copyright" and will use the English words instead. To be able to find the correct stylesheet, Publican versions below 0.43 need the language to be called fr-FR and versions from 0.43 onwards need it to be called fr-FR or fr. But fr_FR will apply the po files but not the stylesheet for French. --Rlandmann 06:50, 7 May 2009 (UTC)

ahhh, this is a good catch. I wondered about whether it made sense to use fr_FR since this is closer to what all the other apps use. For F11, the release notes used fr-FR which took a little fiddling around with the po's, but not much. I expect Transifex could deal with fr-FR anyway, although there was some discussion about whether fr wouldn't be a better choice. --McD

Historical Note
This approach was initially chosen for the simplicity of determining the appropriate string by using the locale(1) output. The build tools also recognize the LANG environment variable.

Another Note
At least on the Fedora 10 Live CD, the LANG environment variable is not always set consistently. --McD

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 yelp. The remaining documents are left for the user to discover in /usr/share/doc/HTML. What is the right answer?

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.

---

Let me elaborate on this a little further.

Currently, fedora-release-notes.rpm contains six documents.

• fedora-release-notes - Publican - displayed in yelp and also provided as html on disk

• about-fedora - f-d-u - displayed in yelp

• homepage - f-d-u - provided in html

• readme - f-d-u - provided in text

• readme-live-image - f-d-u - provided in text

• readme-burning-isos - f-d-u - provided in text

When a user logs in with Gnome, the release notes and about-fedora are on his menu in his local language. The others are provided in a number of languages, but the user must fish around for his own language. There are no menu entries provided, so the user must discover them in /usr/share/doc/HTML/.

Evidently, the XML version provided for yelp does not work well with KDE, so there seems to be a consensus that we should only provide html with a menu selection. That can be done more or less automatically by Publican for one language. Publican currently produces RPMs for one language at a time, and I see no evidence that it can change that menu choice based on the user's login language (I could be mistaken, tho).

Rudi has the non-Publican documents ready to go in Publican, so figuring out how to make all the Publican stuff as automatic as possible seems like a productive avenue. We can then pretty well leave fedora-docs-utils to history.

Currently, Publican does not produce the .omf files needed by yelp, those were produced by a script for Fedora 11. However, if there is no need for yelp, that is not an issue. There is, however, a KDE help system similar to Gnome's which might provide a smoother user experience than plain HTML, as Yelp provides for Gnome users. That, of course, begs the question as to whether we should do something for XFCE users, and then what about WindowMaker, blackbox, Enlightenment, fluxbox, icewm, lesstif, matchbox, Pek, ratpoison ...

--McD

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?

I don't see a reason to keep using fedora-doc-utils, if we are going to use publican for some docs we might as well use it for all of them, no need having to maintain a second utility. - Users:Zoglesby

One advantage to this approach is that these documents would look nicer, and would carry the Fedora branding. --McD

I'm happy to volunteer to do these. --Rlandmann 06:52, 7 May 2009 (UTC) I've got Publicanised versions of these now. Languages other than English will need a little fine-tuning from translators, and to avoid the merge-and-split dramas, I'll make them available after Transifex is updated to version 0.6. (Assuming that we agree that we want these documents built in Publican). --Rlandmann 06:46, 14 May 2009 (UTC)

We need to seriously look at the bug list for Publican and either work to get those that we consider blockers addressed internally or work with upstream very dilligently. --David Nalley https://bugzilla.redhat.com/buglist.cgi?component=publican&product=Fedora

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 /usr/share/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.

The homepage is, I believe, the default page for a browser to display if the browser is not otherwise configured. It is also a fall-back page when the browser cannot load an external page, such as the network is disconnected. IIRC, it was after Fedora 7 that the Project decided to use the start.fedoraproject.org destination instead. I have always personally considered it a browser defect to not use this page when offline. It can be maintained as a simple page that requires very little updating and new translation, once set. OTOH, if no one cares to maintain it, why bother? -- 08:01, 2 May 2009 (UTC)

Turns out there is a bug on this, https://bugzilla.redhat.com/show_bug.cgi?id=445621 Also, I did discover that lynx uses this if no URL is given --McD

I disagree with Karsten about there being a bug if this page is not shown. Currently, the page shows a search box which doesn't do anything if you're offline. Seems pretty unhelpful to me. When this page was invented Firefox did something pretty hard to understand and not user-friendly -- but now the default "You're not connected" page is quite a bit more friendly. Most browsers give out a "You're offline" message, which is really what users ought to see. --stickster 01:02, 4 June 2009 (UTC)

We have almost as many browsers as window managers. I wonder what the behavior of all those oddball browsers is when this page is missing. And perhaps if we keep this page, it might say something like did you know you're offline. --McD

I did notice another browser using this, Seamonkey I think --McD

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 methods and tools could support this in actual practice.

Can we get a cheat sheet

Currently, tagging in the wiki is very uneven, and not always translatable into xml markup without a lot of knowledge on the part of the author. We have all sorts of pages on how to write for the wiki, but these tend to be long, rambling prose that may be reasonable to read, but easy to forget.

What we need is a single page that lists wiki markup and corresponding xml markup, with no excess flowery prose to confuse the issue. This could become a quick reference for authors that doesn't take the energy that the current documents require to pull useful nuggets.

Along with this we might see if we can move toward markup that is more easily reflected in xml (at least for release notes where the ultimate target is xml). Some markup (e.g. <code>) translates directly to xml, while others (templates in particular) are very error-prone when making the conversion.

1. F12 #ReleaseNotes !Publican