Docs Team ideas for UDS

[Jim Campbell]

Hi All,

About a week-or-so ago, I found out that I received sponsorship to attend
UDS in Budapest. I'm sure you are all as shocked about this as I was . . . I
don't recall if we've ever had a documentation person sponsored to attend
UDS.

I'm excited, though, and I want to make the most of it. I am going to send
along some session ideas to the UDS organizers, but wanted to involve folks
from the docs team before I did that.

Here are some of the topics that I had in mind for discussion.  What do you
think? Feel free to share your input around any of these ideas, and we'll go
from there.

Scope of on-disk help. Kyle N. had brought up this topic on the ML, and I
thought it would be good to talk about it as a group, and to also get input
from non-doc-team folks at UDS.
- What help should be shipped on-disk, and what help should be on the web?
- What amount of on-disk help is appropriate for the docs team to handle?
- At this time I don't think the docs team is in a place to create / install
/ configure a documentation CMS. If Canonical wants more non-wiki, web-based
help, what kind of resources would be available for such an effort?

Alternate / non-official help on the web
We've always had supplemental help sources out on the web, but now Canonical
folks and project leaders are using these non-official means of distributing
Ubuntu help and news. I think that part of why they are going elsewhere is
because these sites are popular, and they are also kind of filling a gap
that isn't being met by the docs team. Here are a couple
thoughts on this.
- askubuntu.com is a super-helpful site, but it's voting system can pose
some challenges for writing user help because the tips provided by Canonical
users can get voted up and become the official help, when a more open
process may work better. (I'm thinking of Unity terminology)
- Webupd8 and OMGUbuntu. Help that is contributed to Webupd8 is licensed as
CC-by-NC, so we can't include it in the Ubuntu help, which is licensed as
CC-by-SA 3.0.
- OMGUbuntu content is Copyright OHSO.co. It's proprietary, so we can't
include it in Ubuntu help.
- Leveraging askubuntu.com CC-by-SA data dumps. Askubuntu provides XML data
dumps of questions and answers under the same license as Ubuntu docs. We can
mine this for user questions, but will need a focus on what help should be
on-disk.
- Thinking of creating a Documentation Team blog to funnel *some* of these
topics through more Ubuntu-doc-friendly channels - Integrate these "tips"
with the Ubuntu docs team work.
- I don't want to discourage people from using Askubuntu, sending tips to
OMGUbuntu or Webupd8. Just want to streamline the process of getting topics
into official docs where it is appropriate.

Preferred Help Layout for the System docs
- With Mallard, we have a few different approaches to laying out the help
topics with Mallard. The layout of help topics isn't internally consistent
in our help right now, and this issue is also present in the Gnome3 help.
- Would designers / UX folks be willing to do some UX testing to help us
find out which help-topic layout would work best for users?

Preferred Help Format
- Within the Ubuntu ecosystem, we have docs written in DocBook (Server help
and some application help), Python-Sphinx (the Ubuntu Packaging Guide),
Mallard (system documentation, some applications), LaTeX (the Ubuntu
Manual), and some official help is on the wiki (UbuntuOne help). Of course,
we have the wiki itself, too.
- Should we look to consolidate, or are we ok with these different
approaches? What is working well?

Future challenges for Gnome application help
- Some Gnome application help is not going to work for Ubuntu anymore. For
example, official Empathy help will reference the Gnome-Shell messaging
tray. Will need to work with upstream, and perhaps adapt Mallard to address
these issues.
- How to manage this within the docs team?

Touch-based user interfaces
- In what ways should we be exploring help for the uTouch work?
- What kinds of help interfaces are best for touch-based computing?

Community building. Getting more contributions to docs from more people.
- A Docs Team blog to let people know what we are doing
  - Share ubuntu-relevant help tips that we come across from the web
  - Share information and links on information architecture, XML work, Gnome
help work, etc.
  - Docs team blog posts to showcase Ubuntu as a platform for working on
user help.
- Regular team meetings. Even if we can't all make it, scheduling them out
and having them at set intervals so that we can have a more steady
contribution cycle and have better docs.

Those were some of the topics that I had in mind. Are there any other
big-picture things that you think would warrant some discussions at UDS? I
left out stuff about accessibility and translations, but I would like to
talk with people from those teams, too.  If you have ideas or suggestions,
feel free to share them.

Thanks, all.

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20110426/4a0c4319/attachment.html>