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 ([email protected]) 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 ([email protected]) 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 ([email protected]) 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_ ([email protected]) 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 ([email protected]) 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 ([email protected]) 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_ ([email protected]) 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 ([email protected]) 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
_______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
