Docs Team Planning

Registered by Jeremy Bicha on 2011-11-02

We need to identify areas where the Ubuntu documentation is lacking, improve our own documentation of how to get involved, and advertise to recruit contributors to help fill in the missing documentation.

Blueprint information

Status:
Started
Approver:
Ubuntu Documentation Project Team
Priority:
Medium
Drafter:
Jeremy Bicha
Direction:
Approved
Assignee:
Ubuntu Documentation Project Team
Definition:
Discussion
Series goal:
Accepted for precise
Implementation:
Started
Milestone target:
None
Started by
Kate Stewart on 2011-12-08

Related branches

Sprints

Whiteboard

Work Items:
[jbicha] cleanup/update https: //WIKI.UBUNTU.COM/DOCUMENTATIONTEAM/SYSTEMDOCUMENTATION/TASKS TO PRUNE OUT TASKS THAT WERE DONE, AND WHAT STILL NEEDED.: TODO
[jbicha] Come up with documentation (getting started) on making barrier as low as possible for new contributors - planet ubuntu posts to attract.
publicize areas that need help creating content after unity, server on WIKI
[david.wonderly] ensure that Kubuntu information on the Documentation Team Wiki ( https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks ) is up to date: DONE
Add to developer.ubuntu.com - Developer API documentation - forward linkage to QT, and possibly area for revision.
[kate.stewart] ask unity team to review existing help documentation, and make suggestions of features that need further explanations.:BLOCKED
[kate.stewart] ask server team for liason to the docs team.: DONE
[petermatulis] server team to review the missing list.: BLOCKED
[kate.stewart] ask support team for liason and what are pain points: DONE
[davidbensimon] support team to contribute known pain points to task list.: INPROGRESS
[kate.stewart] set up editorial help sign up sheet to help with technical overview, release notes, and broadcast.:DONE
[mpt] open bug against web team/update manager to point to more user level documentation about the release (bug 885720): DONE
We need to get more translated screenshots into the system help

Notes:
20111208 - KS: server team contact for coordinating the docs is petermatulis / pmatulis

Discussion from http://summit.ubuntu.com/uds-p/meeting/19874/other-p-documentation-planning/
Transcribed over on 2011/11/09

https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation
* https://help.ubuntu.com/11.10/ubuntu-help/index.html
   - See the beta version with new branding: http://mdke.org/tmp/help.ubuntu.com/
* https://help.ubuntu.com/11.10/serverguide/C/index.html

support.mozilla.com - approach, theming, etc. for consideration? sumo approach?
ask ubuntu audience to help fill out this site.
experience is pretty dull.

Do people read documentation on disk?
Any user testing?
Unity - not having help menu. Invisible.
   Help on the launcher?

After feature freeze - Tab key to switch between lenses.
Unity developers to review help?

Missing Content
==========
* We need quite a bit more Unity-specific how-to and explanation.
It would be nice to get some Unity devs to look at the documentation and point out new features. As an example, I had no idea that pressing the tab key switched between lenses until Oneiric was nearly released.

* Developer documentation of the Ubuntu-specific libraries (appindicator, Unity lenses, etc.) is very lacking (or at least not very discoverable). Of course, the Docs Team generally doesn't have the expertise to write this (as we're often not programmers).

* We had some nice contributions this cycle from the Server Team working on the Server Guide.
  - https://juju.ubuntu.com/docs/ Ought to be linked to in the Server Guide

* Consistent terminology
  - Menu bar, system/session menu, the Ubuntu button/Dash home
  - How to describe lenses and scopes so it is easy for users to understand

Help Needed
========
* Advertising specific things we need help with to attract new contributors.
   * Release Notes - rework templates to make useful for specific audiences at different parts of the cycle
   * Editorial help - signup for folks willing to help edit the technical overview and release notes prior to publication
* Ubuntu Studio looking to ramp up this, this cycle as well.

In help document - ctrl-L - gives URL

Own documentation for docs team is out of date. Tasks - needs updating, some in system help.

Example developer.ubuntu.com/resources/platform/api >> packaging >> Help needed example. Getting more of the help needed examples.

Consistent themeing with the developer.ubuntu.com
Juju has different format, different themeing ... inconsistent.

At release time:
Technical overview - text based web page
User overview - Why or why not want to upgrade (part of update manager)

Good examples:
http://library.gnome.org/misc/release-notes/3.2/
   - What's new for users, what's new for developers; and translations. Can we aim at this sort of approach?
http://docs.fedoraproject.org/en-US/Fedora/16/html/Release_Notes/index.html
http://www.kubuntu.org/news/11.10-release

Actions
======

[jbicha] cleanup/update
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks
prune out tasks that were done, and what still needed.
[jbicha] Come up with documentation (getting started) on making barrier as low as possible for new contributors - planet ubuntu posts to attract.
[ ] publicize areas that need help after unity, server on WIKI
[david.wonderly] ensure that Kubuntu information on the Documentation Team Wiki ( https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks ) is up to date: DONE
[ ] Add to developer.ubuntu.com - Developer API documentation - forward linkage to QT, and possibly area for revision.
[skaet] ask unity team to review existing help documentation, and make suggestions of features that need further explanations.
[skaet] ask server team for liason to the docs team, and to review the missing list.
[skaet] ask support team for liason and what are pain points and contribute to task list
[skaet] set up editorial help sign up sheet to help with technical overview, release notes, and broadcast.
[skaet]
[mpt] open bug against web team/update manager to point to more user level documentation about the release.
[] We need to get more translated screenshots into the system help

(?)

Work Items

Dependency tree

* Blueprints in grey have been implemented.