Release notes have a launcher - maybe we should remove that

[Philip Whitehouse]

I'm not a WG member, so take these comments as you will.

On 2014-08-29 23:06, Pete Travis wrote:
> 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.

Maybe we can target Fedora 22 for this then if necessary. The original 
bug was raised about 2 years ago, it's not going anywhere..

> 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...
> 

This clearly goes both ways. The original bug was obviously discussed 
extensively by docs, with some rather impolite responses given to the 
original reporter, which is not particularly conducive for a 
re-engagement. Brigading on both sides is not constructive. This affects 
lots of people, most importantly the Fedora end users (such as everyone 
who is now rapidly trying to leave XP :)).

>> 
>>> 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.
> 

You are complaining about introducing a non sequitur, but your answer 
seems to be that in order to help people find information about things 
Fedora does that are unconventional and unexpected we should continue to 
provide this information primarily by a method that is unconventional 
and unexpected. This seems like very faulty reasoning to me.

Release notes, however you wish to spin it are not an *application*. 
Talking about involving the relevant parties, have we had feedback from 
people on the Usability SIG as to whether it is confusing to have to 
look in Applications for something that is not an Application?

FWIW I genuinely had no idea Fedora 20 had a release notes item in the 
applications menu. I wasn't looking for it there. I'm unconvinced how 
helpful it is and the argument that 'it should be everywhere because 
then people will find it sooner or later' is pretty thin to me - it just 
starts to look messy.

If we want to highlight the release notes we put it in their home folder 
and maybe even look into how to make it open on first boot of Fedora. 
This is the logical place I feel. Personally I'd add it to their desktop 
but you have to add extensions to get that to happen in Gnome 3.

It is possible that we still have to fix GNOME Help and put it there 
instead (which feels like the best place to me), but dismissing removing 
the webpage shortcut from the applications list is not a reasonable 
position.
>>> 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.
> 

I really hope we are talking about presenting users with documentation 
in a format that is appropriate for the GNOME environment, not whether 
we present it at all. Certainly all the focus in this thread has been 
about how to make it available in other ways.

> 
> 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?

A search finds files and documents, as well as applications.

The Applications menu shows applications. I think there is a definite 
difference here. If Release Notes launched an application rather than a 
web page shortcut it might be debatable.

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

Philip Whitehouse