Release notes have a launcher - maybe we should remove that

[Pete Travis]

On 08/29/2014 07:26 AM, Elad Alfassa wrote:
> On Fri, Aug 29, 2014 at 4:09 PM, Pete Travis <lists at petetravis.com> wrote:
>> This seems like [another] case of "we want to show all available desktop
>> files without filters, but that looks cluttered, so all other packages
>> should change so we don't have to add filters."  I appreciate the work
>> you're putting into the details on the default install, really, but as has
>> often been pointed out it will be really easy to gain that clutter back with
>> Software.   Two things can change here; *all* packages shipping desktop
>> files, or the *one* displaying them.
> If your criticism can't be constructive, don't say anything.
Please stop proposing disruptive changes so late in the release cycle.
We're into alpha freeze now, it isn't a good time to tweak things that
touch release criteria.

Please take a collaborative approach to dealing with issues when they
touch on other groups' products and priorities.  I don't have a problem
with the Workstation WG making their own choices, but your proposals
affect others.  Bring the discussion to stakeholders, we're not
uncompromising about these things.  If you leave other contributors out
of the discussion, it leads to the inference that you are unhappy with
their work, unwilling to voice your concerns or address them
cooperatively, and are deliberately obfuscating controversial decisions
in the hope that noone will notice and disagree with you.  I don't think
that's what is actually happening here, but you asked for constructive
criticism...

>
>> That said, users *should* have Release Notes, by default, offline, and
>> discoverable.  Fedora changes a lot between releases, and I sincerely
>> believe that taking the extra measures to expose users to this documentation
>> helps alleviate frustration and prevents dissatisfaction when something
>> doesn't work as expected.  What seems obvious in context isn't always so
>> apparent to those on the outside of your process.  A measurable portion of
>> users will look for the reasoning and recommended remedies for unexpected
>> things they encounter.
> No other operation system comes with the release notes bundled with
> the OS. This is not really a thing users *expect*.
Are we trying for parity with other operating systems?  The point seems
a bit non sequitur, but to address it directly: Fedora is different from
other operating systems. The purpose of the Release Notes is to
communicate that.  There are a lot of complaints about unexpected
behavior and confusion following each release in the support venues I
monitor, so yes, I think the extra exposure really does help.

>> Not everyone will simply think "oh, I can install that firewall config tool
>> with Software, I'm just going to accept that and not question it or look for
>> more information."  Some will look for RNs, some will look for speculative
>> forum posts, some will look for blog posts, and some will look for *you* to
>> *personally justify* your actions.  Our goal is to provide all of these
>> people the information they need to understand the behavior they encounter
>> and achieve the behavior they want.  It's a service provided by the Docs
>> team to both users *and* developers.  The benefits outweigh the pain of
>> having an icon that you aren't that interested in.
> I don't understand what's the problem with having the release notes
> available on the web and linked to in the download page and in the
> support page.
There's no problem with those things. More exposure is better - and
remember, part of the goal here is to represent *your work* to your
users.  I want people who install Fedora Workstation to understand the
design goals and purpose of Workstation, the features it offers, and how
to use it.
>
>> As a maintainer of that package, I'd welcome specific suggestions or
>> requests to improve presentation.
> Few options:
> * Instead of installing a launcher, make it available in
> gnome-documents or yelp. You can separate the launcher to a subpackage
> for desktops that don't care about the application model or having a
> consistent user experience.
> * Do nothing. We can exclude the release notes from the Workstation
> media. It will still be available in the web.
>
>
I don't buy the idea that presenting users with documentation conflicts
with a consistent user experience.  If anything, presenting the Release
Notes as a GNOME product rather than a Fedora product, but only in
Workstation, is not consistent for this package.


Meanwhile...
On 08/29/2014 07:30 AM, Matthias Clasen wrote:
> Before chiming in on this discussion, I figured I should look at what we
> actually ship as the release notes.
>
> Here is what I get on f21 when trying to launch fedora-release-notes.
> $ gtk-launch fedora-release-notes.desktop
> gvfs-open: file:///usr/share/doc/fedora-release-notes-20/index.html:
> error opening location: Error when getting information for file
> '/usr/share/doc/fedora-release-notes-20/index.html': No such file or
> directory
>
> I'm not easily discouraged, so I pointed manually at the right file:
> gvfs-open file:///usr/share/doc/fedora-release-notes/en-US/index.html
>
> This succeeds in opening a web browser, with a page that reads:
>
> This document provides the release notes for Fedora 19...
Ugh... fair point.  At this stage in the release cycle, we're still
writing copy. I have a draft with 'this is a pre-release made for
testing, please report bugs to bz and feature observations to docs'
around somewhere to bridge the gap, and will add that to my list for
this weekend.
> I think this nicely illustrates some of the downsides of locally
> installing frequently changing content, in particular if this is not the
> sole (or primary) means of publication:
>
> It breaks, it gets outdated, and nobody notices.
It changes *a lot* prior to GA. After that, it's minor corrections and
translation updates.  If we're talking about the efficacy of the copy
itself, we could always use some help! Keeping track of Workstation
alone has been difficult.

> Given this state of affairs, and the fact that we already bury the
> release notes launcher in the sundry folder, I think it would make a lot
> of sense to instead arrange for it to become pre-seeded content in
> documents, like the gnome-document getting-started guide is treated
> currently. If we do that, the release notes will still show up
> prominently in shell searches, thanks to the gnome-documents search
> provider.
>
>
> Matthias

Bastien replies with a note that PDFs are needed for this - we can do
PDFs.  How does this pre-seeding work in practice?  How does having the
documentation show up prominently in shell searches via this mechanism
better align with the design goals of Workstation, as compared to the
current implementation?

-- 
-- Pete Travis
 - Fedora Docs Project Leader
 - 'randomuser' on freenode
 - immanetize at fedoraproject.org