No documentation for using/configuring Unity

[Jonathan Jesse]

Has the Unity team discussed how they are or will be working with the Ubuntu Docs team to get things documented and in 10.10?

I would be willing to help lead that discussion if that hasnt happened.

[Mirco Müller (macslow)]

Since I'm not sure which ubuntu-docs team to assign to this as being "also affected", I've chosen the "Ayatana-Design" team for the time being.

[Jonathan Jesse (jjesse)]

Mirco,

As a member of the Ubuntu Docs team I would be willing to help with this. One of the things decided is maintain as much documentation within the package as possible. An example would be usb-creator. Documenttion used to reside within the ubuntu-doc package itself but is moving into the usb-creator packages.

Let me know how I can help

[Mirco Müller (macslow)]

I've no experience with writing (and maintaining) application-documentation for Ubuntu-users in any official manner. So any suggestion regarding this I greatly welcome. I would guess that the Design-team would like to see documentation presented in a certain "branded" style... to go along with Unity's slick looks :) So having one of their team-members on board would be helpful too. I'll try to close the loop here. Keeping you posted.

[Mirco Müller (macslow)]

Jesse, I just mailed Marcus Haslam, of Canonical's Design-team. I've also CC'ed you. So the loop is about to be closed :)

[David Siegel (djsiegel-deactivatedaccount)]

jjesse, let's collaborate on this. I can provide Unity specs and any other information you may need. Please ping me -- djsiegel -- in #ayatana.

[Jorge Castro (jorge)]

Hi docs folks,

Currently we have unity.ubuntu.com as the non-geek accessible portal to unity. jjesse how can I help you get what you need on the doc side?

[Jonathan Jesse (jjesse)]

Jorge,

Just got get started

Let me see what I can do

[Jonathan Jesse (jjesse)]

Been thinking into this and wondering, shouldn't this instead be assigned to Ubuntu-docs and the Ubuntu Doc team as it will be the default for Ubuntu 11.04? Seems like it falls right under their role --- documenting the system

[Matthew Paul Thomas (mpt)]

unity.ubuntu.com is not a non-geek portal, it is expressly for potential contributors to the code ("Join the revolution", "Get Involved", etc). This bug report is about fixing the help -- so in the current help architecture, yes, it does belong to ubuntu-docs.

As a simple example of what needs changing, the help for many, many topics includes instructions on launching particular applications. That help needs to be smart enough to use its existing text when Ubuntu 2-D fallback is running, but new text instead when Unity is running.

[Phil Bull (philbull)]

This is a difficult one. Unity is a shell - users don't necessarily see it as an application in its own right - so documentation which only covers Unity might seem weird. The Unity docs should probably be part of the desktop help. An "interface tour"-type document might be a useful addition, along with some more specific topics on points which people are likely to get stuck on. A nice way of keeping the Unity docs in their own package would be to transition the system docs to Mallard. It can deal with this use case very gracefully.

I think the 2D fallback interface will be a real problem. We could probably rig something up to get Yelp to check an environment variable and switch in appropriate docs, but it would be a lot of work and annoying to maintain. It would be a nightmare for users looking at the help on the web too. Is the fallback interface the same as Unity but minus the effects, or is it completely different?

I'd prefer to ignore styling/branding for now, since it can be added in later. Users will forgive crappy-looking docs that are helpful, but they won't forgive shiny docs that are useless.

[Dean Sas (dsas)]

On Tue, Dec 14, 2010 at 23:38, Phil Bull <email address hidden> wrote:
> Is the fallback interface the same as Unity but minus the effects, or
> is it completely different?

IIRC the fallback interface is the current gnome-panel interface.

[Jonathan Jesse (jjesse)]

my suggestion for moving this into the ubuntu-docs package is that any
customization etc will be covered by the ubuntu documentation or if there is
an upstream ever?

On Wed, Dec 15, 2010 at 10:53 AM, John Lea <email address hidden>wrote:

> ** Tags added: udr
>
> --
> You received this bug notification because you are a member of Ubuntu
> Documentation Committers, which is subscribed to ubuntu-docs in ubuntu.
> https://bugs.launchpad.net/bugs/600875
>
> Title:
> No documentation for using/configuring Unity
>
> Status in Ayatana Design:
> New
> Status in Unity:
> Triaged
> Status in “ubuntu-docs” package in Ubuntu:
> New
>
> Bug description:
> Has the Unity team discussed how they are or will be working with the
> Ubuntu Docs team to get things documented and in 10.10?
>
> I would be willing to help lead that discussion if that hasnt happened.
>
>
>

[Mark Shuttleworth (sabdfl)]

Jonathan, if you're willing to take the lead on the documentation, then
I would encourage you to put it in whichever location you think is best.
We would use the same licence as the Ubuntu wiki. If the docs are now or
in future likely to land in trunk then we ask them to be covered by the
contribution agreement.

Cheers,
Mark

[Jonathan Jesse (jjesse)]

Mark,

Unfortunately I am busy hacking away at the kubuntu-docs and can't take the
lead on this. I was thinking more along the fact that within ubuntu-docs
configuring Unity, etc would be covered by the documentation, book, etc.
 Why would this require acceptance of the contribution agreement? Would
every editor/contributer to ubuntu-docs then have to be covered by the
contribution agreement?

On Fri, Dec 17, 2010 at 3:36 AM, Mark Shuttleworth <
<email address hidden>> wrote:

>
> Jonathan, if you're willing to take the lead on the documentation, then
> I would encourage you to put it in whichever location you think is best.
> We would use the same licence as the Ubuntu wiki. If the docs are now or
> in future likely to land in trunk then we ask them to be covered by the
> contribution agreement.
>
> Cheers,
> Mark
>
> --
> You received this bug notification because you are a member of Ubuntu
> Documentation Committers, which is subscribed to ubuntu-docs in ubuntu.
> https://bugs.launchpad.net/bugs/600875
>
> Title:
> No documentation for using/configuring Unity
>
> Status in Ayatana Design:
> New
> Status in Unity:
> Triaged
> Status in “ubuntu-docs” package in Ubuntu:
> New
>
> Bug description:
> Has the Unity team discussed how they are or will be working with the
> Ubuntu Docs team to get things documented and in 10.10?
>
> I would be willing to help lead that discussion if that hasnt happened.
>
>
>

[Mark Shuttleworth (sabdfl)]

On 19/12/10 02:05, Jonathan Jesse wrote:
> Unfortunately I am busy hacking away at the kubuntu-docs and can't take the
> lead on this. I was thinking more along the fact that within ubuntu-docs
> configuring Unity, etc would be covered by the documentation, book, etc.
> Why would this require acceptance of the contribution agreement? Would
> every editor/contributer to ubuntu-docs then have to be covered by the
> contribution agreement?

No, I was referring specifically to anything which it makes sense to
check into the Unity tree, so that it is available and current on other
OS's that adopt Unity.

Mark

[Matthew East (mdke)]

This bug raises an issue about how the ubuntu-docs team can stay
relevant following Ubuntu's switch to Unity.

Phil has raised a thread about this on the mailing list, which you can
read here:

https://lists.ubuntu.com/archives/ubuntu-doc/2010-December/015358.html

I'd encourage Unity developers to review it and give their thoughts
because how the ubuntu-docs team proceeds could also depend on what
the Unity team's plans for documentation are, and indeed the extent to
which Gnome will continue to be Ubuntu's upstream project.

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

[Mark Shuttleworth (sabdfl)]

Thanks for the pointer, Matthew.

 * On Mallard, I think that's a decision for the folks who do the work!
I see tool evolution / replacement as inevitable over time. I would hope
we could always be trying to get closer to the goal of better
cross-desktop commonality in that, but even within GNOME there will be
iterations and evolutions.

 * The divergence in shell is what it is. Even though Shell has evolved
to look similar to Unity, there will always be areas of divergence. We
can / should / will document Unity itself, but I recognise there will be
linkages between that and the clean documentation of individual apps.

 * Encouraging collaboration between ubuntu-docs and the Ubuntu Manual
Project seems healthy to me.

To a certain extent, it's incumbent on us to document the whole,
integrated platform, from boot manager to upstart to Unity. We've never
been vanilla anything! That's more obvious now, but has always been the
case.

We have a similar challenge with developer API's, which we'll start to
address this coming year. We need to present the complete platform, the
sum of all our choices, in a coherent fashion.

Mark

[David Stevenson (david-avoncliff)]

As an user, I think the first thing to document is that there are a number of different desktops, how to recognise which you are running and how that choice was made.

[Moses Moore (moses-mozai)]

11.04 'natty' was released on 2011-04-28.
/usr/share/unity/doc/ is still empty, and there's no 'unity-doc' package.

[Matthew East (mdke)]

Natty has documentation for Unity in the gnome-user-docs package, shipped by default, and available on the front page of the help center ("yelp"). It needs some more polish, much of which has been done in bzr and will be uploaded to natty-proposed in the next few days.

Marking as fixed from the ubuntu-docs team perspective as the current version of gnome-user-docs in natty addresses this issue. Please feel free to file any bugs on the documentation separately.

[Omer Akram (om26er)]

Yelp, explains quite a bit on how to use unity.