Help has GNOME shell screenshots and documentation

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?

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.

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

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.

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?

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

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.

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.

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?

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.

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

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

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.

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

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.

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

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

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

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

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

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

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!

Fixed in natty-proposed

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