Help has GNOME shell screenshots and documentation

Bug #753072 reported by Kyle Nitzsche
70
This bug affects 11 people
Affects Status Importance Assigned to Milestone
gnome-user-docs (Ubuntu)
Fix Released
Medium
Unassigned
Natty
Fix Released
Medium
Unassigned

Bug Description

Binary package hint: ubuntu-docs

When you launch yelp (command line 'yelp') the docs shown do not appear to be about Ubuntu/Natty.

For example, they don't describe things in the context of unity, unity-2d, or even "classic" gnome desktop.

A following set of questions is:

 * what Ubuntu content is needed?
 * of that, what part should be on-disk, and what part should be online?
 * how should online Ubuntu help be arranged?
 * translation of these?

description: updated
Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

A following set of questions is:
 * what Ubuntu content is needed?
 * of that, what part should be on-disk, and what part should be online?
 * how should online Ubuntu help be arranged?
 * translation of these?

Revision history for this message
Vikram Dhillon (dhillon-v10) wrote :

Kyle: I will be adding #1 to the description as that makes it easier for us to see the concerns brought up. Thanks.

I believe this would be a feature request, all the other docs are included, the docs regarding unity haven't been written and updated to include the 2-d stuff afaik.

description: updated
Changed in ubuntu-docs (Ubuntu):
status: New → Triaged
importance: Undecided → Medium
Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

Medium? How about the many individuals of the world who have never used or have rarely used a computer. I'd like them to use Ubuntu/Natty and easily get the help they need.

I propose that we want to reach and help them, but we want to do it in a way that does not create unnecessary work (development and translation) and maintenance.

My personal view for on-disk Ubuntu docs is:
 * as few docs as needed
 * as many as required
 * translated

So, high, or maybe even critical.

I am wondering if we should also create a cool and vibrant online docs area. It could theoretically be like this:
 * core docs (translation)
 * submitted docs that get user reviews
 * editorial team that reviews highly rated submissions and promotes them to core

Changed in ubuntu-docs (Ubuntu):
importance: Medium → Critical
Revision history for this message
Jim Campbell (jwcampbell) wrote :

At this time there still aren't Natty docs, and I agree that this is critical. I'm going to be doing some initial work of porting over what I can from the gnome-user-guide that we are just wrapping up, and will have an early branch available for feedback tomorrow.

I'll comment on this bug report and will send a note to the ML with a link to the branch once I have it up.

Revision history for this message
Matthew East (mdke) wrote :

Jim - note that there is already a branch for upstream gnome here: https://code.launchpad.net/~ubuntu-core-doc/gnome-user-docs/natty. It can easily be merged with the latest upstream changes which are here: https://code.launchpad.net/~vcs-imports/gnome-user-docs/trunk. I will do that now.

The problem is that they are based on Gnome 3, and not Unity.

There are two ways to fix this. One is that we edit it to try to make it fit Unity. The other is that we try to update the ubuntu-docs package to try to make it fit Unity, and then point yelp at that. I don't have any feel for how different Unity and Gnome 3 are. If they are very different, the second solution might be preferable. Any thoughts from you or Phil who have worked on the Gnome documentation?

Revision history for this message
Matthew East (mdke) wrote :

The gnome-user-docs/natty branch is now up to date with latest upstream.

Revision history for this message
Jim Campbell (jwcampbell) wrote :

I'm going through the Gnome docs, splitting out the docs into a few categories
- Docs that are relevant only to Gnome (the shell overview / introduction topics)
- Docs that can be used as-is, or with minimal porting to Ubuntu
- Docs that are relevant, but would need moderate refactoring for Ubuntu

There are also some topics that are relevant only to Ubuntu (app indicators, unity-specific features, etc.)

I have a good amount of time to work on this (really, I do), but we only have about a week and a half / two weeks to get this stuff in.

Revision history for this message
Phil Bull (philbull) wrote :

Thanks for working on this Jim. I think most of the GNOME docs will fall into the 2nd category - small modifications will be needed in a lot of topics where the user is instructed to open something in the Activities overview or to click System Settings in the system menu.

Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

It's great that you folks are taking this work up, really!

I do wonder about translations. If the approach is to be mallard, it seems like it is all new content (the new Ubuntu-specific topics), which means all new translations are required. Whereas the previous Ubuntu Help Center was very well translated in some key languages. (I raised the question of moving to mallard and translation regressions this would cause quite a while ago, and suggested some sort of effort be made to quantify this.)

Can appropriate well-translated Ubuntu Help content that is still applicable be re-used in the new context in a manner that enables reuse of the translations as well (perhaps through LP Translation "message sharing")?

In any case, has Ubuntu Translators been notified of what seems to be shaping up to be a pretty big piece of work?

Revision history for this message
Jim Campbell (jwcampbell) wrote :

I've created a branch with some initial unity-specific content here: https://code.launchpad.net/~ubuntu-core-doc/gnome-user-docs/natty-unity

Any of member of the ubuntu-doc-committers team can push to that branch. I'll send a note out to the mailing list with more information.

Revision history for this message
Matthew East (mdke) wrote : Re: [Bug 753072] Re: yelp docs not about ubuntu natty

On 7 April 2011 17:46, Kyle Nitzsche <email address hidden> wrote:
> I do wonder about translations.

It's a valid concern. At present, any approach we take is likely to
result in untranslated documentation, unless we just put out the
documentation which we released for Ubuntu 10.10. If we update that at
all, there will be gaps in translations because there is so little
time left before the release. This will always be a significant gap
because of the number of changes required to account for the move to
Unity. If we reuse upstream Gnome content, the translation gap is
likely to be greater, but we will be able to reuse upstream
translations to the extent that these are available (this is at an
early stage at present - http://l10n.gnome.org/module/gnome-user-docs/
- but will no doubt continue).

We will however be able to update translations after the release.

We could choose to only release updated documentation (even in
English) after the release, and build translation time into that.
However it seems to me that having updated documentation in one
language in time for the release (if that is possible) is better than
no languages. Bottom line is that we are not in an ideal situation and
it is a question of damage limitation.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

Revision history for this message
Matthew East (mdke) wrote : Re: yelp docs not about ubuntu natty

I've subscribed David Planella as he should be aware of this from a translation point of view.

Revision history for this message
AJenbo (ajenbo) wrote :

The deadline for docs has past and since the Maverick docs appears in the natty translation list any translator will think that those are the final docs that will ship with Natty. As the deadline for translation of the docs is in less then 100 hours translation teams are right now probably putting a lot of work in getting them translated. This really seams like poor planning.

If the Maverick docs are not going in to the Natty release then you should remove it from the translation list and send an mail out to the translation list so no further effort is waisted on them.

My suggestion would be to keep the Maverick docs for now, larg parts are still valid, Gnome 2 is still there for any one with 2D only driveres, Gnome 2 is sugested for any one with disability, and Unity as default has even been up for debate recently (http://www.phoronix.com/scan.php?page=news_item&px=OTMwMg). Then focus the energy og making well planed, solid, tested and translated docs for Oneiric.

tags: added: iso-testing
Revision history for this message
Kyle Nitzsche (knitzsche) wrote :

Another bug (754418) was made a dup of this one. That bug noted that current Natty yelp docs are based on Gnome 3, whereas Ubuntu Natty has Gnome 2.

From the ubuntu-docs list it looks like the ubuntu-docs team is working heroically to modify the Gnome-3 set of Mallard topics to make it appropriate for Ubuntu Natty (while perhaps also keeping maverick Ubuntu Docs available for "classic" desktop).

I wonder whether this is the best approach for Ubuntu users.

It raises the question: is content being driven by the toolchain (Gnome 3 Yelp uses Mallard, whereas Maverick Ubuntu Help Center uses docbook)?

(Ubuntu Docs in Maverick was well translated into many languages, and translation of Gnome 3 topics + new Ubuntu Topics is at best uncertain.)

Another approach would be to ask: What do Ubuntu Natty users need for content (on-disk/online)? Then let content development flow from that (with due consideration of delivery formats and localization).

A related question is: how important is it that content be independent from the display application (yelp)?

Revision history for this message
Kate Stewart (kate.stewart) wrote :

While its critical to get this right from the documentation perspective, it isn't a blocker for shipping the release since we can do updates, and improve this over time. Adjusting the priority to reflect release perspective.

Changed in ubuntu-docs (Ubuntu Natty):
importance: Critical → High
Revision history for this message
Matthew East (mdke) wrote : Re: [Bug 753072] Re: yelp docs not about ubuntu natty

On 12 April 2011 23:46, Kyle Nitzsche <email address hidden> wrote:
> It raises the question: is content being driven by the toolchain (Gnome
> 3 Yelp uses Mallard, whereas Maverick Ubuntu Help Center uses docbook)?

No, it's not. We have adopted this approach because (a) the Gnome 3
experience is closer to Unity than the Gnome 2 experience that our
previous documentation reflected, and (b) Gnome upstream have produced
some outstanding help over the last release which is much more user
friendly and helpful than our own. The fact that the toolchain has
been changed to improve the quality of the help being provided is a
bonus, but it's not the driver.

I don't know whether this approach will be possible for future
releases. It will depend, among other things, on how far Ubuntu
diverges from Gnome.

The approach we've adopted won't result in perfect help but it is the
best we can do with limited time, inclination and resources to write
our own help from scratch. Even if we had done so, then I am confident
that the approach taken by Gnome upstream is the right one which we
would have mirrored for reasons which we have discussed on the mailing
list many times.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

Revision history for this message
Jim Campbell (jwcampbell) wrote :

>
> It raises the question: is content being driven by the toolchain (Gnome
> 3 Yelp uses Mallard, whereas Maverick Ubuntu Help Center uses docbook)?
>

I agree with Matthew here. We chose this toolchain (Mallard + Yelp) because
it provided a better user experience (at least in the on-disk context) than
DocBook, and it is easier to write and extend than DocBook.

Besides, the people who were working on Gnome docs are pretty much the same
people who are working on Ubuntu docs. Phil Bull, myself, Tiffany
Antopolski, Natalia Ruz . . . we all helped shape Gnome 3 help and we all
use Ubuntu. (Or at least we use Ubuntu as our primary desktops...).

I'm entirely open to using different tools in the sense that I would be
willing to write for content that goes on the desktop or web, but I'm not a
web developer, and don't have the time and inclination to develop a doc CMS
and get it integrated into the Canonical infrastructure. If Canonical has a
need for a more web-based help system, I think it would be a good area for
them to invest more resources.

> (Ubuntu Docs in Maverick was well translated into many languages, and
> translation of Gnome 3 topics + new Ubuntu Topics is at best uncertain.)
>
> Another approach would be to ask: What do Ubuntu Natty users need for
> content (on-disk/online)? Then let content development flow from that (with
> due consideration of delivery formats and localization).
>

I agree that the even the help we are working on now may need to be
re-architected a bit. The online portion remains a bit of an open question.
Again, I'm open to other (online) approaches.

> A related question is: how important is it that content be independent
> from the display application (yelp)?
>
>
Ryan Lortie and Shaun McCance talked about some additional ideas at the doc
hackfest in Toronto, even talking about getting some help-specific features
into GTK itself. Shaun would be the person to talk to about that stuff.

Thanks for the questions, Kyle.

Revision history for this message
Martin Pitt (pitti) wrote : Re: yelp docs not about ubuntu natty

Now that gnome-docs and ubuntu-docs at least document the unity elements on the first page, I downgrade this to medium. It's fine to update this post-release as well if it doesn't make it in time for the release.

The other sections still have screenshots for GNOME shell, will these still be updated?

Thanks, Martin

Changed in ubuntu-docs (Ubuntu Natty):
importance: High → Medium
milestone: none → natty-updates
summary: - yelp docs not about ubuntu natty
+ Help has GNOME shell screenshots and documentation
Revision history for this message
Jim Campbell (jwcampbell) wrote :

Yes, we will be updating all of the screenshots to feature Unity. It is still a WIP.

Revision history for this message
Matthew East (mdke) wrote : Re: [Bug 753072] Re: yelp docs not about ubuntu natty

On 18 April 2011 11:19, Martin Pitt <email address hidden> wrote:
> Now that gnome-docs and ubuntu-docs at least document the unity elements
> on the first page, I downgrade this to medium. It's fine to update this
> post-release as well if it doesn't make it in time for the release.
>
> The other sections still have screenshots for GNOME shell, will these
> still be updated?

Yes, this is in the pipeline.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

Revision history for this message
Matthew East (mdke) wrote :

Whoops, sorry for the duplicate comment, I missed Jim's because of the change in the subject line on the bug emails.

Revision history for this message
Clint Byrum (clint-fewbar) wrote : Please test proposed package

Accepted gnome-user-docs into natty-proposed, the package will build now and be available in a few hours. Please test and give feedback here. See https://wiki.ubuntu.com/Testing/EnableProposed for documentation how to enable and use -proposed. Thank you in advance!

tags: added: verification-needed
Revision history for this message
Matthew East (mdke) wrote :

Fixed in natty-proposed

Changed in ubuntu-docs (Ubuntu Natty):
status: Triaged → Fix Committed
tags: added: verification-done
removed: verification-needed
Revision history for this message
Martin Pitt (pitti) wrote :

Copied to natty-updates and oneiric. Bug wasn't autoclosed due to wrong source package.

affects: ubuntu-docs (Ubuntu) → gnome-user-docs (Ubuntu)
Changed in gnome-user-docs (Ubuntu):
status: Triaged → Fix Released
Changed in gnome-user-docs (Ubuntu Natty):
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Duplicates of this bug

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.