Discuss doc team goals for the 11.10 release

Registered by Jim Campbell

The 11.10 docs-team goals wiki page [0] outlines the possible doc team goals for the 11.10 release, and there is a separate blueprint to lay-out the strategy for the docs team [1].

This session will allow community input in fine-tuning and prioritizing the 11.10 docs team goals.

[0] https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Tasks/Oneiric
[1] https://blueprints.launchpad.net/ubuntu/+spec/desktop-o-ubuntu-docs-strategy

Blueprint information

Not started
Ubuntu Documentation Committers
Jim Campbell
Needs approval
Ubuntu Documentation Committers
Series goal:
Milestone target:

Related branches



Work items:
[j1mc] Identify the scope for the Ubuntu Docs team this cycle and follow it up on the ubuntu-doc mailing list: TODO
[j1mc] Publish the agreed scope for the Ubuntu Docs Team Oneiric Roadmap in a public location

Session notes:

Ubuntu Documentation Team goals for the 11.10 Release
Create a strategy document for the team
Mission statement:
Create effective user help for Ubuntu users, contributors, and developers for all platforms, and make Ubuntu an attractive and functional platform for technical communicators.
- Develop task- and topic-oriented user help to assist users with completing tasks and resolving problems . . .
- for Ubuntu desktop, server, cloud users, and for contributors and software developers . . .
- in multiple outputs, including web, on-disk, ePub and wiki help.
- List Ubuntu help assets clearly identifying them for scope and responsibility purposes. (This helps determine what NOT to do from the universe of help possibilities)
 * Is the primary deliverable the Ubuntu Desktop Course (formerly known as Ubuntu Help Center)?
  * Server Guide?
 * Application help where Ubuntu is the upstream (for example, Unity, Software Center...)?
 * Application help where Ubunt is not the upstream (for example, Empathy)?
- Develop help in accordance with the Ubuntu release schedule such that it can be translated by the comunity in the usual release schedule
- Model effective user help practices and consult with teams within Ubuntu on creating effective documentation within each of their different teams.
- Ensure that Ubuntu documentation is accessible for people with sight, hearing, or other disabilities or impairments
- Assist with the packaging of and bug fixing of documentation syntaxes and documentation build toolchains
- Work with upstream documentation projects to ensure that software installed by default on Ubuntu is well documented and customized, if needed, for Ubuntu
- Context sensitive help important
- Improving way of reporting bugs about ubuntu-docs (maybe a mailto link that includes the mallard id for the page to start. Point is that the bug interface may be too heavy for doc end users who just want to report a typo or somthing on that order)
Team strategy
- Develop a team strategy document to help guide our decisions on an ongoing basis.
- Work with the a11y team to create a11y test cases for Ubuntu documentation and the GNOME help browser
Upstream work
- Work with upstream software projects to ensure that apps shipped in Ubuntu are well documented. Assign ubuntu docs person to each important upstream app to monitor the help, identify ways it needs to be modified for the Ubuntu experience, and carry those mods out.
- Look to keep content generic (with respect to view) as possible to minimize the downstream customizations that are necessary
--- Contact from LibreOffice. They need help. Who wants to sign up for that?
- Work with upstream to push improvements that we make in help layout to their structures as well
Web presence
- what's the vision? (separate from implementation details) Deserves a dedicated UDS session.
- Update docs to follow Ubuntu branding
(Note the web AND the on-disk docs need to be branded)
- First half of cycle - Work with teams to wireframe and spec-out a better web presence for help.ubuntu.com
- Integration of web and desktop help.
- Ways of featuring community documentation. An editorial board. Ways of featuring helpful blogs and tips.
- help.ubuntu.com to be localized? (YES :) Perhaps a language selector widget to switch user to localized page.
- should initial landing page (post l10n swich) be CURRENT help (and provide less prominent access to previous ubuntu help)
- faster search by hashes ? current search is slow, we could cache it on the server I think
Wiki refactoring and wiki mentoring
- Refactor the docs team wiki pages, with particular focus on the getting-involved wiki pages with a goal of identifying and implementing best practices from around the community
- Keeping pages consistent makes things easier for a11y purposes
- Broad content inventory from across the team wiki pages
Usability and design
- Identify a preferred help layout via usability testing
- Long-term - make sure that the help layout is consistent across user help
 - update style guide
   common style for pages (teams, logs),
   - chapters,
   - ToC,
   - categories,
   - tags,
   - contact
   - copyright
Tech Comm platform
- Content inventory as an initial step for reworking wiki
- Review lists of UX deliverables and identify ones that would be most-relevant for Ubuntu help and produce them.
- Make them available as sample documents for those seeking information on tech comm best practices and to increase interest in Ubuntu within tech comm circles.
Documentation Upkeep
- Natty, Maverick and Lucid SRU's for bug fixes and translations
- Move Server Guide to it's own project to make it easier for server folks to branch it, work on it, and identify bugs (DONE)
- Remove browser start page? Currently not used by Firefox or Chromium, but is used by Epiphany and Midori
- Ship gnome-user-guide as it's own upstream package, moving Ubuntu-docs back into the Ubuntu-docs package (DONE)
- Document Unity 2d fallback
- Docs for Ubuntu One??
- Server / Cloud team docs plans?
--- Most doc team members don't have access to the types of hardware required to document these apps, but they are vitally important.
- uTouch help?
- Getting Ubuntu help feedback / Star rating system similar to the Software Center. Reporting bugs are developer-oriented. How can we allow for reporting of problems in a user-friendly way.
- Language use and documentation conciseness
<UndiFineD> invite people from ubuntu-tour to work on docs
<UndiFineD> their users numbers is large, so it seems those people would like to work on it and need to be mentored https://launchpad.net/~ubuntu-tour


Work Items