2010-01-10 Team Meeting Minutes

[Shaun McCance <shaunm gnome org>]

Here's the minutes of today's meeting.  Full meeting log attached.

Accessibility Documentation
===========================
* Willie explained the current structure of the accessibility
documentation.  Most accessibility technologies have their
own manual, although the Orca documentation is tucked into
the system accessibility manual.
* We agreed the system accessibility help should be rolled
into the system user help, under "Universal Access".
* Shaun asked for a volunteer to provide a rough outline of
what help will live where for accessibility.
* ACTION: Shaun to email Vikrom with general information on
how to outline the accessibility help.
* ACTION: Vikram to create outline for accessibility help.

Mallard Page Templates
======================
* Vikram started working on templates, but is unsure what
actual page types to provide templates for.
* Shaun had stubbed out a Mallard document with templates
and instructions side-by-side.
* Templates should reflect our actual experiences.
* We will put templates in gnome-docu module for now.
* ACTION: Shaun to email Vikram and list with his stubbed
templates document.

Changing the Help Menu
======================
* Phil wants us to put more meaningful content into Help
menus than "Contents" and "About", and to update the HIG
to reflect our recommendations.
* General consensus that this is the right thing to do,
but we need to decide what should go into the Help menu.
* ACTION: Phil to start wiki planning page:
  http://live.gnome.org/DocumentationProject/HelpMenus

Rhythmbox Documentation
=======================
* Jim asked about rewriting the Rhythmbox documentation in
Mallard.
* Shaun pointed out there's been discussion of Banshee help in
Mallard and suggested they share a content planning session.
* Jim and Milo will discuss further.

WritersUA Conference
====================
* Jim brought the WritersUA Conference to the attention of
the group.
* Jim is planning to attend.  Shaun is strongly considering.

projectmallard.org
==================
* Shaun has been working on content for projectmallard.org
using Mallard pages as the source.
* No objections to this approach.
* ACTION: Shaun to discuss technical details with Paul.

xml2po
======
* Claude pointed out concerns with the future of xml2po.
* When gnome-doc-utils splits into yelp-xsl and yelp-tools,
xml2po should be its own module.
* There are concerns that if Danilo takes xml2po to LP,
we'll lose the ability to make updates we need.
* ACTION: Milo to email Danilo (CC Shaun and Claude) about
setting up an IRC meeting to discuss xml2po.

2009 Q4 Report
==============
* Stormy is asking for team reports for 2009 Q4.
* ACTION: Shaun to send documentation team report today.


<shaunm> all right, let's get this meeting started
<shaunm> who's here?
* pcutler raises hand
<^arky^> o/
<philbull> Here
* j1mc o/
<Gwaihir> hello!
<claude> hi
--> WillieWalker (~wwalker 68-112-255-247 dhcp oxfr ma charter com) has joined #docs
* WillieWalker waves "Hi"
<shaunm> and WillieWalker's here
<shaunm> I was just going to type "willie's not here yet.  let's wait until he gets hear to talk about accessibility docs"
<WillieWalker> :_)
<WillieWalker> :-)
<shaunm> so let's start with that so WillieWalker and ^arky^ can go about their days if they want
<WillieWalker> shaunm: you rock.  I have a three hour ride I need to get done today. :-)
<shaunm> so right now, we have an accessibility guide.  and, I think, each of the accessibility tools has their own manual.  is that right?
<WillieWalker> kind of sort of...
<WillieWalker> the orca doc is tucked into the a11y guide
<WillieWalker> it should be pulled out
<WillieWalker> but i believe the rest of the assistive technologies are separate
<shaunm> so two questions:
<shaunm> 1) if all the ATs have separate docs, does that make it harder for the desktop-wide docs to give concrete instructions on things?
<shaunm> 2) can we just roll the desktop-wide a11y docs into the general user help?
<WillieWalker> shaunm: without cross references, yes.
<WillieWalker> shaunm: I think so, (for #2) and we could call it "Universal Access"
<WillieWalker> shaunm: the "without cross references" part is referring to #1.
<shaunm> so we can cross-reference between documents
<shaunm> the only hitch is that if you link to another document, it's sort of like introducing a dependency
<WillieWalker> shaunm: agreed.
<WillieWalker> shaunm: I'm thinking about this page here: http://live.gnome.org/Accessibility/NewPreferencesGUI
<shaunm> and I guess I don't know to what extent we allow or encourage vendors to replace the various tools
<WillieWalker> What I'm going to try to shoot for for 2.32 is that this becomes the main "universal access" control panel
<WillieWalker> It puts all the a11y stuff in one spot, so maybe the docs could be lined up around it.
<shaunm> makes sense
--> dhillon-v10 (~dhillon-v 66 222 202 68 cfl res rr com) has joined #docs
<WillieWalker> shaunm: technically, we kind of have things broken into several areas, though I'm not sure we need to arrange or expose this to the user, but...
<shaunm> so if we're using mallard, we can actually maintain the a11y pages in a separate directory, or even a separate module
<-- dhillon-v10 has quit (Bye)
<WillieWalker> 1) There's stuff in the X Server (AccessX) -- it's controlled by the keyboard properties control panel
<shaunm> maybe that makes maintenance easier (or maybe not)
--> dhillon-v10 (~dhillon-v 66 222 202 68 cfl res rr com) has joined #docs
<-- dhillon-v10 has quit (Bye)
<WillieWalker> 2) There's stuff built into GTK+, such as keyboard navigation.  This applies to lots of people who are keyboard only users
<-- jjardon has quit (Ping timeout: 600 seconds)
<WillieWalker> 3) There's more stuff built into GTK+, such as theming, to allow for colors, fonts, icons, etc.
--> dhillonv10_ (~dhillonv1 66 222 202 68 cfl res rr com) has joined #docs
<shaunm> right, so generally we don't want to organize information by implementation details
<dhillonv10_> sorry I am a little late :)
<WillieWalker> 4) Then, there's extra tools, such as Orca, Dasher, MouseTrap, MouseTweaks, GOK, etc.
<shaunm> dhillonv10_: it's all right.  we're discussing the accessibility documentation
<dhillonv10_> shaunm: great 
<WillieWalker> So, I think all the stuff except the last item (extra tools) could be clumped into one module
<shaunm> yes
<WillieWalker> and Orca, Dasher, et al, would have their own doc space in their own module.
<shaunm> right
<WillieWalker> But, we'd need cross references between the two.
<WillieWalker> Orca will want to point to key nav shortcuts, for example.
<shaunm> and if they need to, they can also plug some pages into the main a11y docs
<WillieWalker> And the core docs will want to point to the extra tools.
<shaunm> all right, so we need to draft a plan for what goes where, do some content brainstorming, and get writing
<WillieWalker> Finally....some users are going to want to read the docs "offline" or perhaps in something like a DAISY doc reader (a document format for people who are blind or visually impaired)
<WillieWalker> So, there needs to be some sort of way to linearize the docs (I think) into some sort of bookish format.
<shaunm> WillieWalker: that's another can of worms entirely
<shaunm> which I'd love to talk about, but it will consume this entire meeting
<WillieWalker> shaunm: no prob.  table it. :-)
<WillieWalker> shaunm: so, it seems like we could focus on mallardizing http://library.gnome.org/users/gnome-access-guide
<shaunm> so are any of the experienced Mallard people here familiar enough with the accessibility technologies to create a rough plan?
<dhillonv10_> possible :)
<WillieWalker> shaunm: and pull the portions that refer to Orca, MouseTweaks, etc., into modules that live with the orca git module, etc.
<philbull> I did the initial merge of the Orca docs into the GAI
<philbull> ...but I'm not that familiar with the accessibility technologies
<j1mc> philbull: GAI?
<WillieWalker> shaunm: and then figure out how to handle the cross references.
<philbull> Sorry, the accessibility guide, getting my acronyms mixed-up
<WillieWalker> philbull: we affectionately call it "gag"
<WillieWalker> :-)
<shaunm> haha
<philbull> that's the one
<^arky^> I  learnt mallard by converting orca technical reference from sgml, and I know a11y 
* WillieWalker looks for ^arky^'s bugs....
<shaunm> 605790 and 604339?
<WillieWalker> https://bugzilla.gnome.org/show_bug.cgi?id=605790 - Orca Technical Reference
<shaunm> so I'd like to move on.  what I want is somebody to volunteer to write up a rough plan.  I can send you an email of what the plan should include
<WillieWalker> https://bugzilla.gnome.org/show_bug.cgi?id=604339 - Mallard document: Gnome shortcuts cheatsheet 
<WillieWalker> Those are the ones (you are right shaunm)
<dhillonv10_> shaunm: me :) 
<WillieWalker> dhillonv10_: you rock.  please feel free to CC me and ^arky^
<shaunm> done
<shaunm> dhillonv10_: I'll send you an email this afternoon
<WillieWalker> I'm happy to try to help with whatever time I might have.
<dhillonv10_> WillieWalker: sure :) I just happen to have some time today so...
<shaunm> (I'll CC gnome-doc-list)
<WillieWalker> I at least promise to review content.
<dhillonv10_> WillieWalker: thanks reviewing is a lot of help :)
<-- andre has quit (andre)
<shaunm> templates next?
<dhillonv10_> shaunm: sure :)
<shaunm> ok, so dhillonv10_ started some mallard page templates
<shaunm> and I actually have some (very light) initial work I did for templates laying around somewhere
<dhillonv10_> what i have so far is the proof of concept, this could make your life easy as a writer
<shaunm> yeah
<dhillonv10_> but don't know what to include in those templates
<dhillonv10_> so maybe a brain-storm of what you guys would like to see in them
<shaunm> so I think it's important we make the templates based on what we actually find ourselves doing as we write
<shaunm> (and, as a corollary, we should feel free to stray from the templates when needed, because that's how templates are born)
<dhillonv10_> shaunm: that too also i want to cover all tips and tricks in mallard so those can be used a reference when needed
<shaunm> what I did (and I'll try to dig this up) was to make a mallard document, with a page for each page type
<shaunm> and that page showed the template inside a <code>, and would provide instructions on how to use it effectively
<j1mc> dhillonv10_: i was thinking of templates for different kinds of apps.
<shaunm> but I only stubbed it out.  I don't think I ever got real content in there
<j1mc> for example - a panel applet template, a medium-sized app template, a config-app template... 
<j1mc> that was just an initial thought, though...
* WillieWalker off to go ride unless you still need me -- I just subscribed to gnome-doc-list so I should get the e-mail sent there.  Many thanks everyone. You guys kick butt and are unsung heroes.
<shaunm> I just fear that templates without real instructions to back them up will encourage people to "fill in the blanks"
<shaunm> thanks WillieWalker
<-- WillieWalker (~wwalker 68-112-255-247 dhcp oxfr ma charter com) has left #docs
<shaunm> j1mc: yeah, good point.  we one kind of template is for individual pages.  but then there's also document templates, i.e. what pages you should actually include
<shaunm> and how to organize them
<dhillonv10_> shaunm: that would really help to get things organized, and easy to use
<j1mc> hm... yeah.  perhaps the "type of page" templates would be better.
<shaunm> I think they both have value
<dhillonv10_> j1mc: yah something like a template on how to include a table, how to include a picture etc.
<shaunm> unless we're providing specific stylistic recommendations on those things, I think those are better served with mallard tutorials
<j1mc> yeah
<dhillonv10_> shaunm: okay :)
<shaunm> dhillonv10_: do you have an account on git.gnome.org?
<dhillonv10_> dhillonv10_: nope sorry, how can I make one
<shaunm> um, instructions are on the wiki somewhere
* dhillonv10_ goes to look up the instructions
<pcutler> shaunm: he'll need a sponsor
<shaunm> you can always commit locally and send patches with "git format-patch" until you have one
<j1mc> really... so many of us learned from milo's work on the empathy help...  what if we selected key doc-sets of several of the different app types...
<j1mc> and had them in a repo
--> obni (~obni a85-139-93-218 cpe netcabo pt) has joined #docs
<shaunm> so how about I find the stuff I stubbed out and send it along to the list
<j1mc> we refine them... and let them serve as best-of-breed examples.  at least initially
<^arky^> how about having templates for creating guides, reference or FAQ
<shaunm> and we can start putting something together in git
<shaunm> we can just shove it in the old gnome-docu module for now
<dhillonv10_> shaunm: seems like I have to be a registered developer, so nvm :)
<j1mc> shaunm: what did you "stub out"?
<shaunm> ^arky^: yeah, all good things
<shaunm> j1mc: basically a mallard document to provide templates and instructions on how to use them
<shaunm> we should move on
<shaunm> anybody have any objections to putting stuff in gnome-docu for now?
<j1mc> is that a repo somewhere?  :)
<shaunm> yeah, it's a repository on git.gnome.org
<dhillonv10_> shaunm: nope, I can just send you my stuff and you can upload it :)
<j1mc> that sounds fine, shaunm 
<shaunm> dhillonv10_: yeah.  I can help you with git if needed
<dhillonv10_> shaunm: after some time when I become a sysadmin I'll have an accont ;)
<shaunm> "Changing the Help menu"
<philbull> That's mine
<philbull> I'm wondering about whether we should try to get something into the next HIG
<philbull> at the moment, the Help menu of an app is very basic
<philbull> just Contents and About
* shaunm hates "Contents"
<philbull> Maybe we should recommend that people put links to 3-4 ket documents in the help menu
<dhillonv10_> philbull: how about including the basic topics in the help menu, like the topics of the main pages 
<shaunm> right
<philbull> I was thinking of more standard items
<shaunm> like what?
<philbull> e.g. "All help topics", "Getting started", "Problems", "Getting Support"
<shaunm> right, I agree
<pcutler> "Tips & Tricks"
<philbull> That way, users can instantly see that the help files might cover a problem they're having (etc.)
<dhillonv10_> philbull: that sound pretty good, now people know what they will find there
<shaunm> I love "Tips & Tricks"
<pcutler> I don't want to see the whole index though
<philbull> pcutler: exactly, or "keyboard shortcuts"
<philbull> we'd have to think about it a bit more
<dhillonv10_> oh and how about including common problems
<philbull> but it gives users a shortcut into the relevant part of the help file
<-- baptistemm has quit (Ping timeout: 600 seconds)
<shaunm> I think we have general consensus that this is the way we want to do Help menus
<philbull> pcutler: we would recommend a limit in the HIG, maybe 5 items max.
<shaunm> it's just a matter of deciding which entries go in
<philbull> are the usability guys updating the HIG for 3.0?
<pcutler> yeah, and if it's 5, one of the 5 needs to be the link to the actual manual too
<pcutler> no
<dhillonv10_> shaunm: we might have to spend a little time on the names we want to choose for the HIG
<pcutler> there was a thread a while back, but there wasn't a lot of interest
<shaunm> one think I want to mention: with yelp 3.0 it will be possible for applications to read yelp's bookmarks
<shaunm> maybe we want to do something with that.  maybe not
<philbull> shall we move this to a wiki page to develop the idea a bit more?
<shaunm> yes
<dhillonv10_> philbull: write a spec :)
<philbull> heh, yes
<shaunm> we're not going to hammer it out perfectly in the next 15 minutes
<philbull> shall I just drop it under http://live.gnome.org/DocumentationProject/HelpMenus
<shaunm> that sounds good
<dhillonv10_> sure
<shaunm> shall we move on?
<shaunm> Rhythmbox documentation
<j1mc> thanks, shaunm 
<j1mc> from the ml, someone proposed to work on updating r-box docs back about a year ago
<j1mc> but they weren't updated... i wanted to see if we could rewrite them in mallard
<j1mc> i would be willing to pitch-in, but would need at least some help
<j1mc> you may ask... why r-box docs, jim?  
<philbull> j1mc: weren't they updated?
<Gwaihir> j1mc, I was thinking about doing it for the 3.0 release
<philbull> I thought there was a bug?
<j1mc> there is no mention of the jamendo... magnatune
<j1mc> at least from the TOC
<Gwaihir> and in this case a mallard rewrite would be really good, Ubuntu will insert a new feature in the next release, and they surely need to document it...
<shaunm> so I think there's also been a lot of discussion about doing banshee in mallard
<pcutler> yeah, I'm working on banshee, albeit slowly
<j1mc> Gwaihir: yeah... that was my thought, actually.
<pcutler> though I did get a new volunteer who's helping
<Gwaihir> pcutler, we can target both rhythmbox and banshee for the 3.0
<shaunm> (not to derail)
<j1mc> Gwaihir: i could help set an outline with you, and then we could get help from the ubuntu doc team
<Gwaihir> and maybe find some common topics to share
<j1mc> good idea
<Gwaihir> j1mc, cool, I'm happy with that
<j1mc> shaunm: what about derailing?
<shaunm> the only reason I bring it up is that rhythmbox and banshee writers could probably sit down together and share a lot of their brainstorming
<Gwaihir> yeah
<j1mc> yeah - think that's a great idea
<Gwaihir> that would be really awesome
<dhillonv10_> true :)
<Gwaihir> desktop help summit maybe? ;-)
<shaunm> maybe
<j1mc> Gwaihir: probably before then
<dhillonv10_> Gwaihir: what's desktop help summit ?
<shaunm> I would really like us to brainstorm the user guide replacement there
<Gwaihir> http://live.gnome.org/DesktopHelpSummit2010
<j1mc> i have to go in about 8 min...  have a condo assn meeting.
<dhillonv10_> Gwaihir: thanks a bunch :)
<shaunm> j1mc: does ubuntu ship rb as its default music player?
<Gwaihir> shaunm, yeah, that will be big
<j1mc> Gwaihir: and pcutler - be in touch about banshee r-box docs?
<j1mc> shaunm: yes
<Gwaihir> j1mc, ok, no problem
<shaunm> j1mc: ok, if you want to talk about the WritersUA conference in eight minutes, go for it :)
<j1mc> cool.  i just wanted to let people know about a conference i went to last year in case people would be interested
<j1mc> http://www.writersua.com/ohc/index.html
<shaunm> it's right after the desktop help summit
<j1mc> yeah
<shaunm> I'm strongly considering going
<j1mc> like, it starts the day after
<shaunm> i.e. it starts on our hackfest day
<j1mc> check out the tracks: http://www.writersua.com/ohc/tracks.htm
<shaunm> (unfortunately.  sorry for the bad timing, folks)
<j1mc> scott nesbitt from dmncommunications.com will be presenting there, as will the community lead for openSUSE
<shaunm> (Zonker might be at the summit, btw)
<j1mc> yeah
<j1mc> i just thought i would mention it to folks in case they were interested.
<shaunm> ok
<j1mc> thanks, all.
<Gwaihir> thanks, j1mc
<shaunm> so the only other thing on the agenda is projectmallard.org
<shaunm> so I kind of eschewed our drupal setup a short while ago, and starting putting together a site that's actually built from mallard pages
<shaunm> http://www.gnome.org/~shaunm/projectmallard/
<shaunm> are people interested in this approach?
<pcutler> no concerns here
<philbull> looks good!
<philbull> I have ideas for tools, BTW
<Gwaihir> I like it
<shaunm> philbull: good, I like ideas
 pcutler|away pcutler
<shaunm> pcutler: so you're hosting projectmallard.org right now, right?
<shaunm> I think, long-term, we want to have an automatic build system triggered by git hooks
<shaunm> but for right now, somebody can build locally and scp the content
<dhillonv10_> I gotta go, thanks a bunch, and you guys rock :)
<shaunm> thanks dhillonv10_
<-- dhillonv10_ (~dhillonv1 66 222 202 68 cfl res rr com) has left #docs
<shaunm> all right, I think everybody is padding off
<claude> if the agenda is over, i just want to ask about xml2po status
 pcutler|away pcutler
<claude> unfortunately danilo is not here
<shaunm> the agenda is over, I think.  pcutler: you and I can chat about the technical stuff whenever you have time
<shaunm> claude: so what do you have in mind?
<claude> i'm very embarassed
<shaunm> taking it out of gnome-doc-utils is the right thing to do.  it's just unclear where it should go
<claude> i invested some work on it, because danilo was unresponsive
<claude> now he claims to work on it again, but I don't see things going further currently
<claude> if he takes it on launchpad, i'm afraid we'll be locked out of the game, sort of
<claude> can we, should we, enforce that it stays on git.gnome.org?
<shaunm> well
<claude> he's the listed maintainer
<shaunm> but I'm the gnome-doc-utils maintainer
<claude> right :-)
<shaunm> I don't particularly mind it being hosted elsewhere, but I think it's essential that we have some control over it
<shaunm> intltool was moved to LP, wasn't it?
<claude> it was
<claude> and dobey is still active on it, but for xml2po I didn't see any serious work by danilo for a long time
<shaunm> yeah
<shaunm> so I'm splitting gnome-doc-utils up into yelp-xsl and yelp-tools'
<shaunm> yelp-xsl already exists.  I'll split yelp-tools off later
<shaunm> and when I do, I think it makes sense to split off xml2po, to wherever it's going, at that time
<-- dino has quit (Leaving.)
<shaunm> claude: you have xml2po changes that could be applied to master?
<claude> yes, particularly https://bugzilla.gnome.org/show_bug.cgi?id=597216
<shaunm> and they're uncommitted because danilo mentioned he was doing something different that would conflict?
<claude> I think so
<claude> and it's a rather significative rewrite
<shaunm> all right
<Gwaihir> can we just get danilo one day and sit down with him to talk about this? I doubt he wouldn't find one hour of time...
<shaunm> that would be really nice
<claude> +1
<shaunm> I really don't want to have some nasty hurt-feelings fork situation.  I like danilo.
<Gwaihir> may I try to write an email to him with you guys in CC? or if somebody else want to do that...
<shaunm> I was just going to offer, but if you want to do it, please do
<shaunm> I've actually emailed him once already.  maybe it would be good to get an email from someone else
--> dino (~dino hnvr-4dbd60cd pool mediaWays net) has joined #docs
<Gwaihir> np, I can do that... (after dinner though :-)
<claude> thanks guys!
<shaunm> cool
* Gwaihir goes hunting the fridge
<shaunm> we'll figure this out, I'm sure
<shaunm> let's officially close this meeting so I can go through the log and write a report
<shaunm> wait, just so it's in the action items in the minutes:
<shaunm> shaun is to write the documentation team 2009 Q4 report and send it to stormy today
<shaunm> if anybody has anything to add to that report, please send it to the mailing list soon