Meeting Minutes 2010-03-28

[Shaun McCance <shaunm gnome org>]

Meeting Agenda
--------------
* With weekly meetings, creating a new wiki page for each
  meeting is cumbersome.
* Milo suggested one page per month.
* Shaun wants to put a meeting notice on the front page.
* Milo asked about ics file. Shaun plugged Blip. Again.

Shared Help System
------------------
* Shaun and Rich Johnson discussed a shared help system
  last weekend at the Desktop Help Summit.
* Shaun to send a synopsis to various lists for input.

Evince Mallard Help
-------------------
* Phil has been working on Evince help in Mallard:
  http://gitorious.org/evince-mallard-docs
* Phil asked about collapsible sections in Yelp. Shaun
  said it's doable. Paul asked if content shouldn't be
  moved to separate pages.
* Milo pointed out problems with linking to anchors when
  sections are collapsed. Shaun said we can auto-expand.

Stub Pages
----------
* Phil suggested at the docfest last week having Yelp
  recognize .page.stub files when in editor more. Useful
  for distro stubs or for testing plugin documentation.

Desktop Help
------------
* Phil, Milo, and Shaun brainstormed the desktop help:
  http://mail.gnome.org/archives/gnome-doc-list/2010-March/msg00121.html
* Phil and Milo will start stubbing pages in a few weeks.
* Phil suggested IRC + Wave for more brainstorming.
* Phil suggested a Docs Jam.

Keywords
--------
* Shaun asked about adding keywords to Mallard to help
  autocomplete search. He pointed out "iPod" completing
  to the Sync page in Banshee as a useful example.
* Phil worried about people writing crappy titles with
  catch-all keywords, giving confusing results.
* Shaun suggested desc could contain specific terms.
* Paul worried about need to use ™ with product names.
  Legality unclear. Ask Luis.

Help Button
-----------
* Phil brought up his idea of having Help buttons show a
  menu of relevant topics to give users more confidence
  clicking them.
* Shaun suggested straightforward method of programmers
  specifying topics. Phil said it was not very Mallard-y.
* Shaun thought of putting together a library that would
  provide Help buttons and menus, populated automatically
  from tags in the help. Put writers in control.
* There was much rejoice.

-- 
Shaun McCance
http://syllogist.net/

<shaunm> all right, let's start
<shaunm> who's here?
* philbull waves
* Gwaihir is Milo Casagrande
<shaunm> pcutler: ping
<shaunm> well, let's get into it.  people will delurk
<shaunm> I'd like to discuss how to handle weekly meetings on the wiki
<shaunm> creating a new wiki page for each meeting is cumbersome
<Gwaihir> one wiki page per month?
<Gwaihir> splitting up the wiki page in 4 sundays
--> billyoc (~billyoc cpe-68-174-120-78 nyc res rr com) has joined #docs
<billyoc> presente
<shaunm> hi billyoc
<billyoc> What news from Chicago?
<shaunm> Gwaihir: hmm, that could work. should we keep the agenda for each for posterity?
<shaunm> billyoc: let's hit that topic next
<Gwaihir> shaunm, maybe expand the agenda with meeting minutes on the same page
<shaunm> well, what I've been doing for the minutes is sending them to the list and just linking to the list archives from the wiki
<shaunm> it's easier for me
<Gwaihir> agreed
<Gwaihir> so we can keep the agenda, it's only a bunch of lines of text
<Gwaihir> and link from the wiki the mail archives
<shaunm> yeah
<shaunm> and I'd also like to put a notice of when the next meeting is right on the from DocumentationProject page
<Gwaihir> do we have some sort of iCal online where we can put the meeting?
<shaunm> *ahem* blip *ahem*
<Gwaihir> (that would be awesome to have)
<shaunm> yeah, we need to get blip running. it can associate schedules with teams, projects, and sets, and you can subscribe to them
--> andre (~andre g1 blanicka25 net) has joined #docs
<shaunm> ok, let's move on, unless somebody has a works-right-now solution for an ical file
<shaunm> next topic: Desktop Help Summit
<shaunm> nixternal and I talked about the differences in how gnome and kde install documentation and reference it with a URI
<shaunm> and I think we came to a conclusion on a shared system
<shaunm> I need to send this off to some mailing lists to get feedback
<Gwaihir> any follow up from the fd.o mailing list?
<shaunm> I think I'd first like to send it to gnome-doc-list and kde-doc-english, and after a first round of comments send it to xdg-list
<Gwaihir> wiki page explaining this?
<shaunm> no, unfortunately
<shaunm> I'll try to send an email today
<shaunm> should I send it to any developer lists, or are the documentation lists good enough?
<Gwaihir> maybe desktop-devel?
<shaunm> yeah
<billyoc> If devs paid attention to that sort of thing, we wouldn't be here today.  ;)
<Gwaihir> probably some packaging people are subscribed to that one and could be interested
<shaunm> hah!
<billyoc> hehe
<shaunm> yeah, that's a good point
<shaunm> what about the distro lists?
<billyoc> yes
<Gwaihir> oh yeah...
<shaunm> ok, this is going to be a long CC list
<shaunm> who has other things to report from DHS?
<philbull> I wrote some evince help
<philbull> There's a gitorious repo for it:
<philbull> http://gitorious.org/evince-mallard-docs
<philbull> Please check it out and give feedback
<shaunm> have you been in touch with the evince maintainers?
<philbull> not yet
<philbull> I'd like to work on the structure more
<philbull> it needs a cardsort doing on it
<philbull> one thing did crop up while i was writing it
<philbull> Would it be possible to implement a style hint in Mallard for expandable sections in Yelp?
<philbull> I have a couple of topics which I think would benefit from having sections folded up, but which would be expanded when clicked
<shaunm> I thought about that before. I didn't do it because nobody had asked for it. I'm trying to only implement features that people want.
<philbull> I think there's a good use case
<shaunm> I agree
<philbull> If you have the gitorious checkout, look at "Moving around a document"
<pcutler> I don't understand having sections folded up when you can use the Mallard sub-pages / menus for that
<billyoc> philbull: I see that section now.
<philbull> pcutler: Sometimes, a certain section fits into a topic, but the page becomes slightly too long to navigate comfortably
<philbull> I could turn it into a Guide page and link off to smaller subpages, but that can feel a little awkward in some topics
<pcutler> I'd rather have longer help than folding something up - I think users miss it
<shaunm> oh man, just used autocomplete to get to that page. *LOVE*
<billyoc> nice
<philbull> pcutler: it would be an optional "style" hint
<philbull> I think the Windows help makes good use of it
<philbull> It's good when you're presented with options: the user only needs to read one section, but all of the sections belong in the same topic
<Gwaihir> extreme case: user perform a search for a topic that is folded up, reach that page, and see only the title
<shaunm> philbull: this looks really nice, by the way
<philbull> shaunm: thanks. It still needs work, though
<Gwaihir> could be misleading, but I like the idea of using (carefully) a folding up option
<shaunm> Gwaihir: we can auto-unfold. I've done that for a certain commercial project I worked on
<philbull> Gwaihir: we should advise against that in the style guide
<philbull> it should also be very obvious that the section title is meant to unfold
<shaunm> yes
<shaunm> and we need to consider the a11y impact
<Gwaihir> auto-unfold would be neat
<shaunm> ok
<shaunm> anything else from DHS?
<shaunm> should we discuss our topic brainstorming on monday?
<philbull> yes
<philbull> http://mail.gnome.org/archives/gnome-doc-list/2010-March/msg00121.html
<philbull> One thing that did crop up was how to handle stub pages for distros
<shaunm> philbull suggested stub pages with a .page.stub extension
<philbull> these would only be viewable in Yelp's "Editor mode"
<philbull> unless the stub was renamed
<shaunm> yeah, and we wouldn't install them
<philbull> We should probably get feedback from distro packagers on this
<philbull> I think it sounds broadly sensible, though
<shaunm> I think this would also be useful for anybody creating plugin pages. their pages need to link to upstream pages that won't exist in their source layout. so they could use stub pages to replicate upstream pages for testing
<philbull> yes, that's a good idea
<shaunm> I did add editor mode on monday.  it displays revision information and editorial comments
<shaunm> I just need to make it pick up stub pages in editor mode
<shaunm> I don't think it affects packagers. we wouldn't even put the stub files in the released tarballs
<shaunm> so we did some brainstorming for "files and folders" and "internet and networking"
<shaunm> it's not a fully fleshed out plan, of course
<shaunm> and there are many other parts of the desktop help
<shaunm> I think we need to do brainstorming sessions on irc
<philbull> maybe IRC + Google Wave
<shaunm> they are awesome in person, but we don't have enough in-person opportunities
<philbull> something where we can live-edit
<shaunm> yeah
<shaunm> or etherpad
<philbull> before we do any more, I think we should work on stubbing the existing ones out
<philbull> it's going to get difficult to manage - we'll have so many topics
<shaunm> all right, how do we want to go about doing that?
<philbull> I'll have some free time in a week or so
<philbull> I was going to go through and do ~30 pages or so over the weekend
<shaunm> awesome
<Gwaihir> I'll have more free time after mid April...
<philbull> others should join in, though
<philbull> perhaps it would be nice to do a "Docs Jam"
<shaunm> yeah
<philbull> have lots of people working on it simultaneously
<shaunm> when would we want to schedule them? append them onto our normal meetings?
<philbull> Maybe
<shaunm> all right, we can discuss that on-list or next week
<shaunm> move on?
<philbull> yep
<shaunm> page icons
<shaunm> anybody want to discuss them, or is the list discussion fine?
<philbull> Oh, I didn't reply on-list yet
<philbull> I'll do that later
<shaunm> all right
<philbull> I think it's going to be hard to get them to convey the right message
<philbull> (Microsoft and Apple probably have whole departments working on this sort of thing)
<shaunm> yeah, um, I met the Microsoft people last week
<shaunm> while it's certainly true that we could learn a thing or three
<shaunm> do not assume that they've thought of everything. we're doing a lot of cool new stuff
<shaunm> ok, unless anybody has something to say, we can just keep that discussion on-list
<shaunm> I'd like to discuss adding keywords to pages, for a very specific purpose
<shaunm> I blogged about the autocomplete search feature I added to yelp. it does a substring match on the title and desc
<shaunm> this, by the way, is a good incentive to write good descs, using synonyms
<shaunm> I thought it would also be good to match on some key words that aren't in the title or desc
<shaunm> specifically, the case that made me think of this was the Sync page in the banshee mallard docs
<pcutler> tomboy
<shaunm> "ipod" should really autocomplete to that page
<pcutler> dammit, need to finish that page too
<pcutler> oh, sorry
<pcutler> you say sync, and all I think of is Tomboy now  :/
<shaunm> but I don't want to put it in the title of the page, and I'm not sure it belongs in the desc
<shaunm> haha
<billyoc> So yelp can act like 'apropos'.
<Gwaihir> will those keywords be written by docs writer right?
<shaunm> keywords could also be weighted higher in full text search, giving us a way to game the search results
<shaunm> Gwaihir: yeah
<philbull> I'm not sure about this. We risk returning search results that may not seem relevant to the user, even though they are.
<shaunm> in the info
<Gwaihir> will it work with i18n?
<shaunm> <info><keywords>iPod Neuros ...</keywords></info>
<shaunm> Gwaihir: it should. it's just another element that xml2po would pick up
<philbull> I see that it could be useful if you have lots of quasi-synonyms for a word (like with MP3 player names)
<philbull> but there is a potential for mis-use
<shaunm> true
<shaunm> mallard is all about potential for mis-use ;)
<philbull> Maybe an example:
<philbull> Page title: Install deCSS support
<philbull> Desc: Allows you to decrypt DVDs and other copy protected media
<shaunm> (can we legally ship that page?)
<pcutler> yes
<philbull> Keywords: DVD playback
<philbull> In this case, the author has chosen a *horrible*, user-unfriendly page title
<pcutler> we're not shipping the codec, so no patents violated, we're just telling someone how to go get it and you make a comment that's it's applicable in specific countries
<philbull> but it's still returned as a relevant search result
<philbull> and the user doesn't understand that it's relevant to them, because all they have to go on is the title/desc
<shaunm> mmm
<philbull> I know for a fact that people will do this, because they do it already!
<shaunm> so when Matthew Ellison was discussing this feature in his presentation wednesday, he specifically talked about being confused when there are results that don't even contain the text you typed
<billyoc> ooh, i hate that.  
<philbull> I guess you could display the keywords on the search result page *only* if a page is matched by keywords
<shaunm> so maybe the solution for the iPod case is that the desc should contain common device names
<shaunm> "Sync your media to an iPod, Zune, or other portable media player"
<philbull> shaunm: I think so. Descs can be quite long (does Yelp truncate them?)
<shaunm> (I have no idea which two to three are the most common, but iPod is certainly #1)
<shaunm> yelp does not truncate them, but it could if it becomes a problem
<philbull> You just put the list at the end of the desc, e.g. "Sync your media to a portable media player (such as an iPod, Zune, XXX, YYY, ..."
<shaunm> I don't think we need to list everything
<philbull> In that case, no, but if you have a 6-7 item list, for example.
<pcutler> I don't think we should list any brand names
<pcutler> in the title / description
<shaunm> people will search on them
<philbull> pcutler: I disagree, people use them colloquially
<philbull> define:colloquially
<pcutler> so does search bring back results for titles & descriptions or the whole help?
<pcutler> philbull: that doesn't make it right
<shaunm> especially "iPod".  iPod people think iPod == portable music player
<pcutler> if it's the whole help, I"d put it in a paragraph
<shaunm> ok, so there's two search systems.  there's the quick autocomplete search, and there's the full text search
<philbull> pcutler: what do you find uncomfortable about using brand names?
<shaunm> autocomplete search only uses the title and desc of the page
<shaunm> full text search (not implemented yet) does the entire page contents
<pcutler> philbull: two things: you can never list them all or get the popularity right, and I don't like seeing registered trademark symbols in titles or descriptions
<shaunm> maybe it's ok that searching for "iPod" means using the full text search
<philbull> I'm hazy on the legal aspects of this
<philbull> Are we forced to use TM/R symbols?
<pcutler> technically, yes
<shaunm> we are not legally obligated to put ™ symbols next to anybody's trademarks
<pcutler> shaunm: so downstream is responsible for that when shipping GNOME software commercially?
<shaunm> they're not legally obligated to do it either
<pcutler> that has not been my experience in the past when defending marks
<philbull> Newspapers can happily reprint the word iPod or Zune without TM symbols
<philbull> when are they supposed to be used?
<shaunm> it's the name of a thing, and you can refer to a thing by its name
<shaunm> companies put the symbols next to their own marks to tell you that they're trademarked.
<pcutler> that's not necessarily correct - when journalists do it, they are writing about the specific device, not a whole class of devices
<pcutler> they may say iPod and other mp3 players, which is fine
<shaunm> ok, three non-lawyers arguing about trademark law.  why don't we just email luis?
<philbull> OK, IANAL, so I'm happy to defer to someone who knows the law behind this
<pcutler> +1 
<shaunm> other topics to discuss?
<philbull> I agree with pcutler that TM/R signs are hideous, though
<shaunm> they are
<shaunm> (the evolution manual is full of them, iirc)
<philbull> hmmm, someone needs to take a look at that manual...
<shaunm> oh, um, right, um
<pcutler> I actually have been using Evolution for the last few months and cracked the manual a while back.  Holy crap is it huge
<philbull> oh, I had an idea for a new UI for help buttons
<shaunm> ooh, yeah
<philbull> When you have a help button (e.g. bottom-left of a dialogue)
<philbull> you click it and a menu with a few relevant topics pops up
<philbull> The idea is that users click it and see that a topic answering their question exists, so they're more likely to click through to the help
<philbull> ATM, people are turned off from blindly clicking a Help button because they've had bad experiences with irrelevant help in the past
<pcutler> gotta run, be back in a bit
<philbull> I don't know how this menu would be populated with topics, though
<shaunm> probably just statically by the programmer
<philbull> that's not very Mallard-y, though
<philbull> e.g. you're looking at the Help button in the "Plugins" dialog
<shaunm> oh oh, just had an idea
<shaunm> but it will require a separate library, and maybe a help manager daemon
<shaunm> probably won't fly
<philbull> try it anyway
<billyoc> yeah
<shaunm> help buttons are declared with some id
<shaunm> help_button_new("preferences")
<shaunm> and pages can insert themselves into a help button with some markup
<shaunm> <gtk:button ref="preferences"/>
<shaunm> oh hell, we could populate menus the same way
<philbull> we have a killer feature, right there
<shaunm> seriously
<billyoc> Where do you need the daemon?
<shaunm> billyoc: just technical details. it could be done without one
<philbull> what about performance penalties?
<philbull> is much processing required to set-up a menu?
<shaunm> one way to do it would be to have a daemon that knows about everything, so apps don't have to compute it all themselves
<shaunm> anyway, not much point in going into technical stuff here
<shaunm> I'll mull this over
<billyoc> philbull: most interface stuff is read from gktbuilder/xml files now anyway.
<shaunm> anything else?
<philbull> I'm finished
<shaunm> cool
<shaunm> I need to make breakfast
<shaunm> fin