January2011

This is a meeting summary and log for the DocumentationTeam meeting of 23 January 2010.

Agenda

  • ...

Summary

  • ...

Log

   1 === head_v is now known as head_victim
   2 [16:54] <Rocket2DMn> Meeting in 5 minutes?
   3 [16:57] <j1mc> meeting in a few minutes
   4 [16:58] <Rocket2DMn> hey j1mc , how are you?
   5 [16:59] <j1mc> hi there, Rocket2DMn :)
   6 [16:59] <j1mc> Rocket2DMn: you are Connor, right?
   7 [16:59] <Rocket2DMn> yup
   8 [17:00] <mdke> evening chaps
   9 [17:00] <j1mc> hello, mdke
  10 [17:00] <Rocket2DMn> hey mdke , long time no see, hope you are well
  11 [17:00] <mdke> happy new year
  12 [17:01] <mdke> not bad thanks, how are you guys?
  13 [17:01] <j1mc> same to you!
  14 [17:01] <j1mc> pretty good here. :)
  15 [17:01] <Rocket2DMn> doing well here
  16 [17:01] <mdke> hey philbull
  17 [17:01] <j1mc> philbull: o/
  18 [17:01] <philbull> hey
  19 [17:02] <j1mc> so far we have myself, philbull, mdke, Rocket2DMn ... anyone else?
  20 [17:04] <j1mc> shall we get started?
  21 [17:04] <mdke> sure
  22 [17:04] <philbull> yep
  23 [17:05] <j1mc> so, i think that the options around the docs have been pretty well hashed-out on the mailing list
  24 [17:06] <j1mc> does anyone have anything to add re: copyright assignment agreement
  25 [17:07] <Pendulum> I have a question, how is this going to effect future people who want to be involved with docs and want to write unity documentation?
  26 [17:07] <mdke> I think that at the moment, enough core contributors object to copyright assignment that we should format plans on the basis that it should not be required
  27 [17:07] <Pendulum> I realise that as a whole the team doesn't want to be involved with it, but does that mean that they'd have to have a separate project?
  28 [17:08] <mdke> Pendulum: I guess that depends on how we decide to proceed. We're not talking about not being involved with unity documentation. If Ubuntu uses Unity, and we're writing documentation for Ubuntu, we'll need to write for Unity
  29 [17:08] <j1mc> Pendulum: i don't think that there would need to be a "unity docs team," but there would be a unity-docs repository
  30 [17:08] <Pendulum> okay, that makes sense. I just wasn't clear :)
  31 [17:08] <mdke> j1mc: would there?
  32 [17:08] <philbull> I had some emails about this from Canonical people
  33 [17:09] <Pendulum> (and as it's about to come up that my team -the accessibility team- is going to be looking for some documentation guidance soon specifically Unity-related)
  34 [17:09] <philbull> They said they'd talk to me in the New Year
  35 [17:09] <philbull> (don't know when; guess they're pretty busy about now)
  36 [17:09] <Rocket2DMn> Would upstream unity documentation exist in the gnome-user-docs?
  37 [17:09] <mdke> Rocket2DMn: I don't see how it can; unity hasn't been accepted into gnome as far as I understand
  38 [17:09] <philbull> Rocket2DMn: No, it won't
  39 [17:10] <j1mc> mdke: if someone wanted to explicity document unity only, i would think that there would need to be a repository for that
  40 [17:10] <shaunm> Pendulum: how much of the accessibility user experience will be the same as with stock gnome in a unity-using ubuntu?
  41 [17:10] <philbull> The gnome-user-docs will be firmly based on gnome-shell
  42 [17:10] <mdke> j1mc: that would be an upstream issue I guess
  43 [17:10] <Rocket2DMn> ok, thanks, i wasn't sure if Gnome was using Unity
  44 [17:10] <Pendulum> shaunm: they're having to write an accessibility framework for Unity so we're not even sure yet because there functionality hasn't made it in yet
  45 [17:11] <Pendulum> (it's due Alpha2)
  46 [17:11] <shaunm> ok
  47 [17:11] <shaunm> Pendulum: but given all the atk bridges and such, orca would still be used for screen reading and braille, yes?
  48 [17:11] <mdke> philbull: I don't think you have commented on the mailing list about the various options, I was interested to find out how you see things
  49 [17:12] <Pendulum> shaunm: orca yes, but I'm not sure any decision has been made about some of the other things -- but I suspect this is a larger conversation that should come outside of this meeting :)
  50 [17:12] <j1mc> mdke: upstream being "unity developers" in this case?
  51 [17:12] <philbull> mdke: First of all, I'm tremendously pissed off about the whole thing
  52 [17:12] <mdke> j1mc: I guess so
  53 [17:12] <philbull> The copyright assignment thing is really divisive
  54 [17:13] <philbull> Whatever we do, we risk wasting our time
  55 [17:13] <mdke> well
  56 [17:13] <zkriesse> Oh doc meeting?
  57 [17:13] <mdke> that's the case of any contributions to Ubuntu, it's not a documentation specific issue
  58 [17:13] <philbull> true
  59 [17:13] <mdke> I feel the same way, but I think it's not a documentation issue specifically
  60 [17:14] <philbull> Yes, but we need to talk about the docs here
  61 [17:14] <mdke> sure
  62 [17:14] <philbull> Ideally, they'd stop requiring the CCA
  63 [17:14] <czajkowski> aye the same could be said about a patch
  64 [17:15] <philbull> My worry is that the same thing will happen with the Unity docs as happened with the gnome-app-install/software-center docs
  65 [17:15] <philbull> We had docs for that, and someone at Canonical just wrote their own and put them directly in the package
  66 [17:15] <j1mc> philbull: i wasn't aware of that
  67 [17:16] <j1mc> philbull: did someone request the ubuntu-doc author(s) to sign the copyright agreement?
  68 [17:16] <philbull> j1mc: Yes, the docs for software-center weren't written by the Ubuntu Docs team!
  69 [17:16] <mdke> mpt wrote them, iirc
  70 [17:16] <philbull> j1mc: Not in that case. As far as I'm aware, we didn't even hear about them
  71 [17:17] <Rocket2DMn> Quick question guys - are there currently any docs for Unity in any format?
  72 [17:17] <mdke> not as far as I know
  73 [17:17] <j1mc> Rocket2DMn: not that i'm aware of... are there any docs from the netbook edition that used the Unity layout?
  74 [17:18] <Rocket2DMn> Not sure, I'm afraid I've been out of the loop a fair amount since we released Lucid
  75 [17:19] <Rocket2DMn> Never did any netbook documentation either
  76 [17:19] <mdke> philbull: that particular issue may have been a problem of lack of communication between docteam and development team; here I think we have a more subtle issue
  77 [17:19] <philbull> mdke: Perhaps, but I wanted to point out that there is precedent
  78 [17:19] <mdke> which is that reasons of principle might prevent us from contributing upstream or to the package
  79 [17:20] <mdke> realistically is there any other option than modifying ubuntu-docs to fit unity and carrying on as before?
  80 [17:20] <Rocket2DMn> mdke, tbh, if you can ever get a development team to communicate effectively and in a timely manner with a doc team,, you're achieving something that few groups have been able to pull off and maintain
  81 [17:20] <j1mc> let's say that canonical develops their own unity-docs package, would it be possible to integrate our docs with it?
  82 [17:21] <Rocket2DMn> Sorry if that sounds skeptical
  83 [17:21] <j1mc> Rocket2DMn: i think that is a problem of many developer/documentor relationships - not just in ubuntu / canonical.
  84 [17:22] <mdke> j1mc: I guess it depends on how it is done. If they follow a similar strategy to gnome-user-docs, and write in Mallard, then I suppose there is no reason why not
  85 [17:22] <Rocket2DMn> j1mc, yes, and as a professional software dev, I know both sides of it
  86 [17:22] <philbull> j1mc: Yes, it wouldn't be as pretty, but it would work
  87 [17:22] <philbull> Especially if they use Mallard. We can just symlink it in (although there may be subtle licensing issues there)
  88 [17:23] <dhillon-v10> philbull: ping
  89 [17:24] <j1mc> philbull: good point re: licensing issues
  90 [17:24] <philbull> mdke: Realistically, I don't think there is any other option but to modify ubuntu-docs
  91 [17:24] <mdke> philbull: me neither
  92 [17:25] <philbull> The modifications wouldn't be too difficult for the most part
  93 [17:25] <philbull> We'd just replace all of the launching instructions with Unity-specific ones
  94 [17:25] <mdke> I haven't tried Unity yet. Is it easy to run in a VM?
  95 [17:25] <mdke> I think I've read that it isn't
  96 [17:25] <philbull> Although there is the issue of the fallback GNOME 2 UI...
  97 [17:26] <j1mc> mdke: like gnome-shell, i don't think it can be run in a VM
  98 [17:26] <Pendulum> j1mc: that's the experience I've had
  99 [17:26] <shaunm> philbull: we don't even have a good docs story for fallback in gnome
 100 [17:26] <Rocket2DMn> I think Unity required 3d acceleration which could make it difficult to run in a VM depending on your setup
 101 [17:26] <Pendulum> there might be a version of virtualbox that will do it
 102 [17:26] <Pendulum> but most VMs can't do the 3D acceleration
 103 [17:27] <mdke> philbull: as to fallback, I think the first thing is to document the default; we have only rarely documented non-default software
 104 [17:27] <Rocket2DMn> Pendulum, i think you're right that vbox can, i'm not sure how good it is though.  Regardless of performance, as long as we can get it to run we can document it
 105 [17:27] <Pendulum> yeah
 106 [17:28] <philbull> mdke: The thing is, lots of people will be experiencing the fallback!
 107 [17:28] <mdke> philbull: really?
 108 [17:28] <philbull> I think so, yes
 109 [17:28] <mdke> oh dear
 110 [17:28] <philbull> It depends on whether graphics acceleration is well-supported, I think
 111 [17:28] <Pendulum> it is also in some ways less of a fallback this time and more of a choice. Both will actually be an option when you log in from the default install
 112 [17:28] <philbull> I've plenty of experience with chipsets that don't like Compiz
 113 [17:29] <mdke> shaunm: can you think of any easy way to provide alternative documentation depending on the desktop used? I can't
 114 [17:29] <philbull> conditionals again...
 115 [17:29] <j1mc> could we just provide a somewhat updated version (or a version with some "note" admonitions) of our current docs for that?
 116 [17:29] <j1mc> ... for the fallback?
 117 [17:29] <mdke> j1mc: the difficulty is how to figure out when it should be shown and when the unity version should be shown
 118 [17:30] <shaunm> mdke: easy way? no, I can't. ideally, the fallback experience would be something that mimics the full experience closely enough that most textual instructions are still correct. but that's not what's happening
 119 [17:30] <j1mc> perhaps provide a topic... if you are using the two-panel gnome layout... use these docs...
 120 [17:30] <mdke> shaunm: nod
 121 [17:31] <mdke> will gnome-shell have similar fallback issues as unity?
 122 [17:31] <shaunm> yes
 123 [17:31] <mdke> doh
 124 [17:31] <mdke> so yelp can't pick up which desktop is being used?
 125 [17:31] <philbull> There is an easy (but hacky) way
 126 [17:32] <shaunm> I'm sure we could figure out a way for yelp to know what desktop shell you're using. an x window property or envar or something.
 127 [17:32] <philbull> We have a script that detects the desktop and launches Yelp with the right documents open
 128 [17:33] <shaunm> if the writers actually have the time to create and maintain dual docs like that, I'll figure out the technical end in yelp
 129 [17:33] <mdke> will the next version of Ubuntu have yelp 3 or yelp 2?
 130 [17:34] <shaunm> I would think 3, but I don't know for certain
 131 [17:34] <mdke> hope so
 132 [17:34] <philbull> If we're shipping GNOME3 apps, we'll be able to ship Yelp 3
 133 [17:35] <mdke> anyway, as you say, it's quite a heavy burden to maintain two sets of docs
 134 [17:35] <mdke> apart from the need to figure out how they should live alongside each other and where they should share the same material
 135 [17:35] <Pendulum> Maybe it's a good time to do some serious recruitment? I know I'm far from the only person who has been interested in documentation for ages but felt like other than wiki work, it was difficult to get involved
 136 [17:36] <mdke> yes, this is something we've struggled with for a long time
 137 [17:37] <Rocket2DMn> There are a lot of things people need to learn to contribute - bzr (and version control in general), docbook, update and release processes, etc
 138 [17:38] <Pendulum> Right, but I have to say that in the past year it's seemed to me that rather than try to teach new people, the default thing has been "here this is what you can do on the wiki". I wonder if there's a way to do doc papercuts so that there are some small things that are easier to use as tools to teach newcomers
 139 [17:39] <shaunm> question: will the gnome 2 fallback be more or less the same in ubuntu as in gnome-shell?
 140 [17:39] <Rocket2DMn> Pendulum, before we get into that discussion, is there more we want to talk about for Unity?
 141 [17:39] <mdke> I'm sure we can do a lot better in that direction
 142 [17:39] <mdke> anyway, before we can figure out how to make contributing easier, we need to figure out what we are going to work on ourselves
 143 [17:39] <mdke> shaunm: I would assume so but don't know for sure
 144 [17:39] <Pendulum> shaunm: as far as I've heard, yes
 145 [17:40] <shaunm> (aside from the differences that already exist, which aren't trivial from a docs perspective)
 146 [17:40] <mdke> indeed
 147 [17:42] <mdke> are the differences so great as to make it impossible to ship single documentation which can be used for both environments?
 148 [17:43] <j1mc> mdke: by "both environments," you mean unity and the gnome2 layout?
 149 [17:43] <mdke> if the differences are just about how to open things or where to find things, we might be able to explain how to do those actions on both desktops, and keep the rest of our language neutral and just refer back to those topics when necessary
 150 [17:43] <mdke> j1mc: yeah
 151 [17:44] <shaunm> in my (limited) experience with unity, it didn't even offer an easy way to get to nautilus. it just has that Files screen. that's a huge chunk of the docs
 152 [17:44] <j1mc> i think that having, "if you are using this desktop, do this..." and "if you are using that desktop, do that..." gets pretty cumbersome as a reader, though.
 153 [17:45] <mdke> j1mc: yes, that's certainly not what I had in mind
 154 [17:45] <j1mc> i experience that at my work, where different teams are using different releases of the same platform, so they have to follow different instructions
 155 [17:46] <j1mc> ... we have 15 min left on our hour's time
 156 [17:46] <mdke> but if we can do instructions like "Open X", with "Open" being a link on how to open applications on each environment, then we at least keep the differences in self-contained places
 157 [17:47] <mdke> perhaps we should experiment a bit with Unity in order to get some ideas about this issue
 158 [17:47] <shaunm> I could add conditional processing in the yelp 3 time frame, but: (1) do people have the time and inclination to maintain conditional docs, (2) the current conditional processing proposal has no way to push or replace contents, which means unity instructions either have to be put into gnome docs, or you'd have to patch
 159 [17:48] <j1mc> yes, i tried alpha1 on my laptop for a bit. i couldn't get unity to work, though.
 160 [17:48] <philbull> I think the plan with Unity might be to go with Zeitgeist/Activity Journal instead of nautilus
 161 [17:48] <philbull> not sure, though
 162 [17:50] <philbull> How about this:
 163 [17:50] <philbull> We do a simple overview of Unity, discussing basic usage
 164 [17:51] <philbull> We replace the "Gnome Shell Overview" in the new GNOME desktop help with that by manually patching it out (no need for Mallard conditionals)
 165 [17:52] <philbull> The desktop help will give us topics on connecting to the internet, managing files and folders, and so on
 166 [17:52] <Rocket2DMn> Another issue that could pop up if we are to select different documentation to display depending on the environment, is how do we deploy our html docs?
 167 [17:52] <philbull> That will give us functional, if incomplete, help
 168 [17:53] <mdke> philbull: when you say desktop help, are you talking about ubuntu-docs or gnome-user-docs?
 169 [17:53] <philbull> gnome-user-docs
 170 [17:53] <j1mc> philbull: the new ones that are being worked-on now?
 171 [17:53] <mdke> so would you jettison ubuntu-docs entirely?
 172 [17:53] <philbull> j1mc: yes
 173 [17:54] <philbull> mdke: Not all of it, but lots of it is already obsolete
 174 [17:54] <mdke> do you think that gnome help is going to be suitable for adoption in that way?
 175 [17:55] <philbull> mdke: Yes, i think so
 176 [17:55] <mdke> my concern is that Ubuntu seems to moving away from Gnome, rather than closer, so if we are moving in the opposite direction, that might not work in the long term
 177 [17:55] <j1mc> mdke: correct, but using what gnome has right now as a jumping-off point would work
 178 [17:55] <philbull> mdke: true, but the GNOME desktop-help is currently split into a number of topic areas
 179 [17:56] <j1mc> ubuntu-docs wouldn't need to stay synced with gnome-shell/gnome-user-docs on an ongoing basis
 180 [17:56] <philbull> we can take whatever is relevant, and its Mallardyness will allow us to do that without too much patching
 181 [17:56] <mdke> is it reasonably complete?
 182 [17:56] <j1mc> but having those mallard topics as a starting point would be helpful
 183 [17:56] <philbull> mdke: Not yet, we need help!
 184 [17:56] <mdke> ok. This is definitely an interesting idea
 185 [17:57] <mdke> although we need to give more thought to it than is available at this meeting, I suspect. In particular we should focus on whether patching in/out material will raise the barrier to entry
 186 [17:57] <Rocket2DMn> I like this, if I'm understanding correctly, we'll be able to use more upstream documentation on basic usage which can replace material we already have
 187 [17:57] <j1mc> philbull: could you provide the git repo information of the current gnome docs?
 188 [17:59] <mdke> let's have a look at the docs, at Unity, think about how much patching will be required, and perhaps have another meeting?
 189 [18:00] <j1mc> mdke: i think that sounds good
 190 [18:00] <philbull> j1mc: Sure: http://git.gnome.org/browse/gnome-user-docs/
 191 [18:01] <philbull> mdke: Sounds good, can you raise this on the mailing list please?
 192 [18:02] <mdke> ok. I will try to summarise the idea and some of the issues on the mailing list and then we can come back, perhaps even a similar time next week?
 193 [18:02] <Rocket2DMn> That works for me
 194 [18:03] <philbull> yep
 195 [18:03] <j1mc> works for me, too
 196 [18:03] <mdke> cool
 197 [18:03] <j1mc> thanks, all!
 198 [18:04] <mdke> catch you soon
 199 [18:05] <philbull> thanks!
 200 [18:06] <Rocket2DMn> mdke, any idea what we need to do for bug 555813 ?
 201 [18:06] <ubot2> Launchpad bug 555813 in ubuntu-docs (Ubuntu) (and 1 other project) "Please, delete the unnecesary es_PR and es_ES templates for ubuntu-docs-about-ubuntu (affects: 1) (heat: 14)" [Undecided,New] https://launchpad.net/bugs/555813

MeetingLogs/DocTeam/January2011 (last edited 2011-03-07 15:38:05 by 208)