1 [20:07] <mdke> no worries, shall we get started?
   2 [20:08] <philbull> sure
   3 [20:08] <mdke> shall we use the bot?
   4 [20:08] <philbull> i guess so
   5 [20:08] <j1mc> i'm not so adept at the bot - i should probably read up on it.
   6 [20:08] <mdke> let's give it a shot
   7 [20:08] <mdke> #startmeeting
   8 [20:08] <nixternal> []
   9 [20:09] <mdke> bot isn't here :)
  10 [20:09] <dhillon-v10> mdke: :)
  11 [20:09] <mdke> oh well, agenda is here: https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda
  12 [20:09] <nixternal> well that would explain everything then :)
  13 [20:09] <mdke> first item: Is moving to Mallard for the system help viable?
  14 [20:09] <mdke> discuss :)
  15 [20:10] <mdke> I'm pretty interested in whether there will be any chance of kde adoption
  16 [20:10] <nixternal> not yet, but possibly in  the future
  17 [20:10] <mdke> I think that will be important for us. nixternal- any idea?
  18 [20:10] <dhillon-v10> mdke: don't know for sure, most of the docs. in kde just got updated
  19 [20:10] <j1mc> i'm fine with writing with it, and it is fine for individual help files.  i have some concerns about widespread adoption.
  20 [20:10] <nixternal> shaunm, myself, and burk from kde will work on it in the future
  21 [20:11] <humphreybc> hi everone, sorry i'm a bit late. it's 9am on sunday morning over here!
  22 [20:11] <dhillon-v10> nixternal: and me :)
  23 [20:11] <mdke> nixternal: will you go to the help summit that Shaun has organised?
  24 [20:11] <nixternal> yes, since it just a few minutes from my house :)
  25 [20:11] <philbull> hey humphreybc
  26 [20:11] <j1mc> nixternal and i are both in chicago, where the help summit will be held
  27 [20:11] <mdke> awesome, that will be a good chance to discuss it
  28 [20:11] <mdke> j1mc: what are your concerns?
  29 [20:11] <mdke> you've been trying it for xfce, right?
  30 [20:11] <j1mc> well, for example... the "administrative tasks" page gets linked to a ton of times from within ubuntu docs.
  31 [20:12] <j1mc> with the auto linking... there would be a lot of links at the bottom of the page linking to related pages.
  32 [20:12] <j1mc> that is just one thing that comes to mind.
  33 [20:13] <mdke> I suspect there would be an element of rewriting to take account of things like that, no?
  34 [20:13] <dhillon-v10> j1mc: possible to have something like a page: "Resources" mentioning all those links
  35 [20:13] <j1mc> mdke: yes - it is just a concern, that's all.
  36 [20:13]  * mdke nods
  37 [20:13] <mdke> has it taken off with xfce?
  38 [20:13] <jjesse> i am trying to make chicago as well
  39 [20:13] <philbull> we can talk to shaun about this
  40 [20:13] <j1mc> also, the linking is designed to be from all within the same folder, if i understand correctly.
  41 [20:13] <mdke> jjesse: awesome
  42 [20:14] <philbull> Mallard is still technically in development
  43 [20:14] <j1mc> philbull: understood.  shaun's doing some cool stuff
  44 [20:14] <j1mc> i would just have concerns about requiring the docs to be all in the same folder if things were to scale up.
  45 [20:15] <philbull> can we symlink?
  46 [20:15] <mdke> yes, me too. I suspect that an ideal structure would really be to have separate folder for the top level tasks. But again, it's something to discuss with upstream
  47 [20:15] <j1mc> yes
  48 [20:15] <starcraftman> oops, lil late, hi people. Been helping with user days. :)
  49 [20:15] <j1mc> philbull: i think symlinking would get messy.
  50 [20:15] <j1mc> welcome, starcraftman
  51 [20:16] <philbull> j1mc: can we do some build magic then?
  52 [20:16] <mdke> philbull: what do you have in mind?
  53 [20:16] <philbull> keep the files in separate dirs in bzr and just put them into the same one when we install the package?
  54 [20:17] <mdke> oh yeah, of course that's doable, if it's the right solution
  55 [20:17] <philbull> it's not as neat as supporting subdirs, i guess
  56 [20:17] <mdke> but wouldn't the top level topics be mallard guide files anyway?
  57 [20:17] <mdke> so they could have their own folder
  58 [20:17] <mdke> and then be brought together by the index
  59 [20:17] <philbull> yes, that's what i was thinking
  60 [20:18] <j1mc> i wonder if you can link to things in other folders... is it just that the auto-linking doesn't work across other folders?
  61 [20:19] <philbull> again, we can ask for a modification to the Mallard implementation
  62 [20:19] <j1mc> in some ways, i liken what shaun is doing to Vala.  Vala is a simpler syntax than C, but it compiles down to C, and people can use existing bindings (I'm not a programmer... but I think this is right).
  63 [20:19] <j1mc> I'm not opposed to this... just want to make sure it will work and that it will scale well.
  64 [20:19] <mdke> well, let's keep discussing with upstream and trying things out. I think the msg from the list was broadly that adoption in this release cycle would be premature - does anyone disagree strongly with that?
  65 [20:19] <philbull> the GNOME user guide will be the acid test
  66 [20:19] <philbull> it'll be huge, much bigger than ubuntu-docs
  67 [20:19] <j1mc> mdke: i think adoption for lucid is premature
  68 [20:19] <philbull> +1
  69 [20:20] <mdke> it doesn't stop us from trying to migrate for fun and giving feedback to upstream to help refine the project
  70 [20:20] <humphreybc> I also think that 10.04 is a bad time.
  71 [20:20] <philbull> we need to be looking into it now, though
  72 [20:20] <humphreybc> Definitely try testing it in another branch now though
  73 [20:20] <philbull> I think experimenting is a good idea
  74 [20:20] <mdke> actually, I think we should keep trying things so that we can be involved in the development of the project
  75 [20:20] <humphreybc> So everyone agrees that a change will have to come this year at some point, most likely in 10.10?
  76 [20:21] <j1mc> shaun and i will both be attending that writersua conference.  it's just too bad that it's immediately after the help summit.
  77 [20:21] <mdke> humphreybc: I think that's a bit early to say
  78 [20:21] <philbull> (need to skip out for 10 mins, back soon)
  79 [20:21] <mdke> humphreybc: we'll keep our eye on upstream and see whether kde get interested too
  80 [20:21] <humphreybc> what are the kde docs like? sorry i've never really used kde
  81 [20:21] <mdke> but frankly Gnome will be moving, and so for ubuntu-docs, moving is more or less a slamdunk decision
  82 [20:22] <dhillon-v10> mdke: one of the *big* problems is that the upstream kde docs. are pretty outdated as well, and a bunch of people will be wokring on updating them as well
  83 [20:22] <mdke> dhillon-v10: the same is true of Gnome
  84 [20:22] <j1mc> mdke: i still wonder - if gnome is finding that it isn't scaling well... what would happen
  85 [20:22] <dhillon-v10> mdke: really ??
  86 === KatieKitty is now known as KatieOffline
  87 [20:22] <mdke> dhillon-v10: totally. they see Mallard as a way of getting people excited about contributing again. They are planning a complete rewrite
  88 [20:22] <humphreybc> ... we could split off from using upstream docs and write our own stuff?
  89 [20:22] <mdke> j1mc: indeed
  90 [20:23] <nixternal> yes, only a few whackjobs want to write documentation, so that is why docs are getting more and more stagnant these days, system docs that is
  91 [20:23] <dhillon-v10> nixternal: :) true
  92 [20:23] <mdke> humphreybc: yes, we could. But that's not really what Ubuntu is about.
  93 [20:23] <dhillon-v10> humphreybc: waaaaaaay to much work,first writing them, then updating and all that good stuff :)
  94 [20:23] <dhillon-v10> *too
  95 [20:24] <mdke> so shall we set up a mallard testing branch? maybe even owned by ~ubuntu-doc or ~ubuntu-doc-contributors so that people can play around?
  96 [20:24] <humphreybc> indeed. but as Ubuntu gets bigger, at some point that might become a necessity. Probably not this year though :P
  97 [20:24] <humphreybc> I think a testing branch is a great idea.
  98 [20:24] <j1mc> mdke: i think setting up a testing branch is ok as long as it doesn't distract from getting good docs out the door for 10.04
  99 [20:25] <dhillon-v10> mdke: sure :)
 100 [20:25] <mdke> humphreybc: I don't really understand. Ubuntu is built out of upstreams, it's only possible because of the reuse of upstream work
 101 [20:25] <mdke> humphreybc: the same reasoning is perfectly valid for documentation
 102 [20:25] <mdke> why would we start from scratch if material can be reused?
 103 [20:25] <humphreybc> mdke: okay fair enough
 104 [20:25] <mdke> ok, let's try and summarise some action points here
 105 [20:26] <mdke> [ACTION] - ubuntu-doc to play around with a Mallard testing branch to test scalability and migration
 106 [20:26] <mdke> [ACTION] - kubuntu-docs to discuss with Shaun in Chicago possibility of KDE migration
 107 [20:27] <mdke> [ACTION] - general liaising with upstream and continued reevaluation with a view to possible migration in lucid+1 or whenever ready
 108 [20:27] <mdke> does that sound sensible?
 109 [20:27] <j1mc> nixternal: shaun was also interested in getting together briefly sometime before the summit.
 110 [20:27] <nixternal> j1mc: I am open
 111 [20:27] <j1mc> mdke: i think that sounds perfectly reasonable
 112 [20:27] <humphreybc> mdke: yep sounds rad
 113 [20:28] <mdke> ok, any other comments on Mallard?
 114 [20:28] <j1mc> not from me for now.
 115 [20:28] <humphreybc> negative
 116 [20:29] <mdke> ok, next topic
 117 [20:29] <mdke> Improving the New to Ubuntu docs - [[DocumentationTeam/Ideas/NewToUbuntu|spec here for discussion]]
 118 [20:29] <mdke> I've sketched out a plan for the new "newtoubuntu.xml" in ubuntu-docs on that wiki page
 119 [20:29] <mdke> I've bashed out two or three quick sections in the bzr branch too so that people can see what I had in mind
 120 [20:30]  * j1mc looks at the page
 121 [20:30] <mdke> any comments on the spec or initial material are very welcome
 122 [20:31] <dhillon-v10> mdke: looks pretty nice, but is is possible to show that doc. up the first time ubuntu starts up, that would make it very helpful :)
 123 [20:31]  * humphreybc also looks
 124 [20:31] <mdke> dhillon-v10: let's keep it in mind but it's something to discuss with the usability team as to whether it would be useful. At the moment yelp startup time is a bit shocking so it may not be a good idea
 125 [20:31] <mdke> although it might be faster starting up an individual document
 126 [20:31] <dhillon-v10> mdke: yaeah working on that with Shaun :)
 127 [20:31] <humphreybc> mdke: that table of contents looks very similar to the first few chapters of the manual
 128 [20:32] <dhillon-v10> *yeah
 129 [20:32] <mdke> humphreybc: the whole manual looks pretty similar to our docs :)
 130 [20:32] <dhillon-v10> mdke: lol
 131 [20:32] <nixternal> I think at best an icon for it either on the desktop of the live cd, or on the desktop after install...usability experts shot down the "popup on startup" idea
 132 [20:32] <mdke> but yeah, it's not innovative thinking or anything, just common sense, I hope
 133 [20:33] <j1mc> it seems like a good start.  i would have to think about it a bit more to really offer any suggestions at this point.
 134 [20:33] <humphreybc> mdke, i thought we'd already discussed this. Either way, you know the plan for the manual. What's the difference between this New to Ubuntu documentation and the manual?
 135 [20:34] <nixternal> its been around for years and gets installed with the ubuntu-docs package
 136 [20:34] <mdke> humphreybc: this is going to be a very short document indeed. I can't speak for the manual though because I've only read the table of contents, not the document
 137 [20:34] <humphreybc> okay so very short, like < 10 pages short?
 138 [20:34] <humphreybc> would it use yelp or a standalone PDF?
 139 [20:35] <mdke> maybe eight pages with about 30 words in each page
 140 [20:35] <mdke> yes, it's for the system documentation, so will be part of yelp
 141 [20:35] <humphreybc> gotcha
 142 [20:35] <AtomicSpark> mdke: I like it. As far as your query, I think it would be best to stick with applications installed by default and once they're up to par, we can think about adding popular (but not installed) apps. However, maybe that should be kept to the community documentation.
 143 [20:35] <j1mc> the manual isn't on the agenda . . . i'd probably rather not discuss it at this point.
 144 [20:35] <dhillon-v10> mdke: could we have like a short description for each topic, then each one linking out to the actual big doc. at the end of each page
 145 [20:35] <mdke> AtomicSpark: that would tend to be my feeling too
 146 [20:35] <humphreybc> j1mc: i know that's why I avoided discussing it, what IS on the agenda however is the fact that much of the manual content can be used for this new to ubuntu thing
 147 [20:36] <j1mc> humphreybc: ok
 148 [20:36] <mdke> humphreybc: have you seen the screenshot lower down the page? That's the sort of detail we're talking about
 149 [20:36] <mdke> for one of the topics
 150 [20:36] <humphreybc> if you have a look at the manual TOC, which will be more detailed for sure, https://wiki.ubuntu.com/ubuntu-manual/TableOfContents
 151 [20:37] <mdke> humphreybc: https://wiki.ubuntu.com/DocumentationTeam/Ideas/NewToUbuntu?action=AttachFile&do=get&target=adding-applications.png
 152 [20:37] <humphreybc> Remember that the manual stuff will be nice and up to date, and will be translated into many languages, as well as having localized screenshots
 153 [20:37] <mdke> that would be chapter 5
 154 [20:37] <humphreybc> ah so it's *very* brief ;)
 155 [20:37] <mdke> well, that's probably more than 30 words, but yes.
 156 [20:38] <mdke> we have other documents covering all of those subjects in more detail
 157 [20:38] <mdke> which are linked to
 158 [20:38] <dhillon-v10> mdke: you just answered my question, thanks :)
 159 [20:38] <humphreybc> righto that's all good then. Yeah just when I read the justification and the table of contents for the "new to ubuntu" project i thought "hang on this looks a bit familiar" :P
 160 [20:39] <mdke> humphreybc: don't be surprised if you see system documents which overlap with the content of the manual. It's more surprising when you see something that *doesn't* overlap
 161 [20:39] <humphreybc> Of course, we obviously have rather nice introduction paragraphs etc for each of our chapters that you are welcome to use
 162 [20:39] <mdke> anyway, if anyone has further comments on the spec, then feel free to send them to the list
 163 [20:40] <mdke> unless anyone has immediate comments, let's move on
 164 [20:40] <j1mc> sounds good.  :)
 165 [20:40] <philbull> I have one comment
 166 [20:40] <philbull> too many notes!
 167 [20:40] <mdke> in the screenshot?
 168 [20:40] <philbull> yes
 169 [20:41] <mdke> that could easily use something else, like a bullet list
 170 [20:41] <philbull> sure, it's just a minor point
 171 [20:41] <mdke> I was carried away by Kyle's frenzied call for images
 172 [20:41] <philbull> he he
 173 [20:41] <j1mc> where is this sample page?  link?
 174 [20:42] <mdke> j1mc: it's the really long link above
 175 [20:42] <mdke> I've done the Welcome and Getting Help sections too
 176 [20:42] <philbull> are the people working on the New to Ubuntu stuff interacting with real users in some way?
 177 [20:42] <AtomicSpark> mdke: which bzr branch are the examples in? lucid?
 178 [20:43] <mdke> AtomicSpark: yep - newtoubuntu/C/newtoubuntu.xml
 179 [20:43] <mdke> philbull: not so far - what suggestions would you have?
 180 [20:43] <philbull> I'm always amazed when I watch new users use Ubuntu
 181 [20:43] <mdke> this arises in relation to the "Common Questions" things in yelp too
 182 [20:43] <philbull> they get stuck on things that you'd never believe
 183 [20:44] <philbull> it's because we're so familiar with this stuff, but it's completely new to them
 184 [20:44] <mdke> I believe that the design team has been doing some user testing that we might be able to rely on
 185 [20:44] <philbull> sure, but are they opening it up?
 186 [20:44] <mdke> Perhaps we could contact them and ask for some feedback or whether we can get access to it
 187 [20:44] <mdke> philbull: we won't know unless we ask I guess
 188 [20:44] <philbull> I asked mpt about getting user testing videos a few months back
 189 [20:45] <mdke> what did he say?
 190 [20:45] <philbull> as far as I remember, he wasn't keen
 191 [20:45] <philbull> I'll have to go back through my email though
 192 [20:45] <mdke> I know that his team is interested in helping with docs though - I bet they just haven't had time yet
 193 [20:45] <philbull> I think they might have been able to give us text reports of user testing
 194 [20:45] <mdke> so if we approach them, they *must* have some way they can help
 195 [20:45] <philbull> not really the same as seeing it for yourself though
 196 [20:46] <philbull> we can all do some limited testing of our own
 197 [20:46] <philbull> I've used my girlfriend and some friends as guinea pigs
 198 [20:47] <dhillon-v10> philbull: I am working on a little feedback system, that can be integrated in yelp so users can just comment from a doc. as they find something they can comment and send feedback right away
 199 [20:47] <dhillon-v10> :)
 200 [20:47] <j1mc> dhillon-v10: i think shaunm was looking into integrating with telepathy for that somehow, too.
 201 [20:47] <mdke> I'd be pretty happy to trust the design team's evaluation of their user testing for our purposes
 202 [20:48] <dhillon-v10> mdke, j1mc: so do you guys think its a good idea
 203 [20:48] <j1mc> mdke: could you rephrase?  i'm not sure what you mean.
 204 [20:49] <mdke> j1mc: well, Phil seemed to be suggesting that we should do our own user testing because we might not have access to the original videos that the design team has done, and just their analysis of them
 205 [20:49] <mdke> I think their analysis of them would be pretty useful, frankly
 206 [20:49] <j1mc> mdke: ah, ok... so you are saying that just seeing their analysis would be... yeah, useful.
 207 [20:49] <mdke> especially since we have limited time to do our own user testing
 208 [20:49] <j1mc> right
 209 [20:49] <mdke> they are experts at user testing, after all
 210 [20:49] <j1mc> yup
 211 [20:50] <mdke> dhillon-v10: I'm not sure, I'd like to think about it a bit more
 212 [20:51] <mdke> anyway, as an action, how about this:
 213 [20:51] <mdke> [ACTION] mdke to contact design team to get their input into what subjects could be covered and where users have common problems
 214 [20:52] <j1mc> sounds greta
 215 [20:52] <j1mc> great :)
 216 [20:52] <mdke> [ACTION] any other feedback on NewToUbuntu to the mailing list
 217 [20:52] <mdke> next item ;)
 218 [20:52] <mdke> Writing an installation guide (The Ubuntu Manual has content for this that can be used)
 219 [20:52] <dhillon-v10> mdke: I have something down, so can that be used
 220 [20:52] <mdke> philbull: you want to sum up status?
 221 [20:52] <philbull> yes
 222 [20:53] <philbull> err, we didn;t get very far
 223 [20:53] <philbull> everyone was too busy
 224 [20:53] <mdke> are those who were interested still around?
 225 [20:53] <philbull> some are, I think
 226 [20:53] <dhillon-v10> o/
 227 [20:53] <philbull> I don't think that having the smaller focused team worked too well
 228 [20:54] <philbull> at the end of the day, we're all volunteers who need to work around other stuff
 229 [20:54] <AtomicSpark> What do we want in an installation guide? Installing from a Live CD and what the available options do?
 230 [20:55] <philbull> the idea was to get people from Windows to Ubuntu in the least painful way
 231 [20:55] <philbull> we already have a detailed installation *manual*
 232 [20:55] <philbull> we don;t want to document every possible installation route
 233 [20:55] <mdke> do we?
 234 [20:55] <philbull> yes, the Debian installation guide
 235 [20:56] <mdke> ah, but that only covers the alternate cd, not the desktop cd, asaik
 236 [20:56] <mdke> *afaik
 237 [20:56] <philbull> yes
 238 [20:56] <philbull> but do we need a detailed manual for the GUI installer?
 239 [20:56] <mdke> AtomicSpark: there is this spec about the planned guide - https://wiki.ubuntu.com/Specs/KarmicInstallationGuide
 240 [20:56] <philbull> or are we better off doing a user-assistance job?
 241 [20:57] <mdke> yeah I agree. The partitioning is a tricky bit but there's no point talking people through selecting their time zone
 242 [20:57] <j1mc> i think an installation "guide" is appropriate here.  having "help" topics for problems would make sense, though.
 243 [20:58] <philbull> j1mc: yes, this is a situation where having something that could be printed off is a good idea
 244 [20:58] <philbull> it's difficult to know exactly what to cover
 245 [20:59] <AtomicSpark> From my experince with other users, I'd say that partitioning is a big hurdle.
 246 [20:59] <mdke> I think the planning for the guide was done pretty well and the table of contents on the spec looks quite good
 247 [20:59] <j1mc> philbull: how far did you get with outlining, drafting and writing?
 248 [20:59] <AtomicSpark> And how exactly dual booting works.
 249 [20:59] <philbull> with the writing, not very far
 250 [21:00] <philbull> all of the other stuff is on the wiki
 251 [21:00] <philbull> so, what are the most common problems that people deal with when installing?
 252 [21:01] <philbull> dual booting and partitioning, definitely
 253 [21:01] <philbull> but also post-install stuff like hardware
 254 [21:01] <philbull> problems with the bootloader too
 255 [21:02] <j1mc> problems with the bootloader are definitely scary for new users.
 256 [21:02] <philbull> so, I think there is a case for providing a brief, basic walkthrough
 257 [21:02] <philbull> lots of pictures etc
 258 [21:02] <j1mc> philbull: what approach could be taken to revive the team around this?
 259 [21:03] <philbull> then separate, focused how-tos (for partitioning/dual-booting) and troubleshooting material
 260 [21:03] <j1mc> that seems like the biggest issue... getting people involved again.
 261 [21:03] <AtomicSpark> Hardware and drivers. Internet stuff like Flash and Java (although we have topics that cover this).
 262 [21:03] <mdke> I think getting the doc into the branch with a structure might help people get involved
 263 [21:03] <philbull> people in the Manual Team might be interested
 264 [21:04] <philbull> I want to write this in plain text first, before we do any markup
 265 [21:04] <mdke> ah
 266 [21:04] <philbull> that should really lower the bar to contribution
 267 [21:04] <philbull> I can mark stuff up in about an afternoon
 268 [21:04] <philbull> there's no point other people worrying about it, the content is by far the most important part
 269 [21:05] <mdke> so there won't be the usual ubuntu-doc QA structure of patch + review by ~ubuntu-core-doc member
 270 [21:05]  * j1mc nods
 271 [21:05] <philbull> AtomicSpark: we have to be careful with what constitutes "installation" and what is "New to ubuntu"
 272 [21:05] <philbull> mdke: not initially
 273 [21:05] <AtomicSpark> True. I was just throwing things up there. ;)
 274 [21:05] <philbull> of course, someone (probably me) edits together a coherent draft
 275 [21:05] <mdke> right
 276 [21:05] <philbull> the peer review can be continuous, but informal
 277 [21:06] <mdke> that's similar to the approach the manual is taking too so perhaps it's worth contacting who is in charge of the installation chapter to see if resources can be pooled there
 278 [21:06] <philbull> sure, that would be a very good idea
 279 [21:06] <philbull> we need to make a firm spec for the installation guide, though
 280 [21:06] <mdke> different to the existing one?
 281 [21:06] <philbull> maybe modify it
 282 [21:07] <philbull> we have to be clear on how it interacts with the New to Ubuntu docs
 283 [21:07] <mdke> I'd suggest modifying rather than starting again, it looks in decent shape
 284 [21:07] <mdke> true
 285 [21:07] <philbull> people are always tempted to start explaining how to add applications
 286 [21:07] <mdke> yes, that sort of thing is clearly not installing Ubuntu
 287 [21:07] <philbull> the IG should be short and sweet, installation only
 288 [21:08] <mdke> agreed
 289 [21:08] <philbull> so, maybe we should discuss this more on-list
 290 [21:08] <philbull> there should be some really fun potential for new contributors here
 291 [21:08] <philbull> some nice, difficult problems for people to explain in a user-friendly way
 292 [21:09] <mdke> will you take it forward on the list then?
 293 [21:10] <philbull> sure
 294 [21:10] <mdke> cool
 295 [21:10] <philbull> shall we move on?
 296 [21:10] <mdke> [ACTION] philbull to raise the installation-guide on the list and plan future action
 297 [21:10] <mdke> yep, next topic
 298 [21:10] <mdke> Setting out a Requirements document to guide our efforts
 299 [21:10] <philbull> this is an interesting idea
 300 [21:11] <philbull> sort of like a manifesto?
 301 [21:11] <mdke> I think what Kyle was saying was basically this
 302 [21:11] <mdke> Discussions on the list sometimes get unfocused because of a lack of understanding about what the team does
 303 [21:12] <mdke> and what it's objectives are
 304 [21:12] <mdke> personally, I think that can be resolved by (a) documenting better what we mean by topic based help, and (b) a rewrite of the style guide
 305 [21:12] <j1mc> mdke: i think it also takes into consideration our own roles as "upstream" doc providers.
 306 [21:13] <mdke> calling it a "requirements document" seems a bit rigid to me, I don't think we really have such things
 307 [21:13] <j1mc> which i'm not so sure we had really considered so much before
 308 [21:13] <philbull> I think having a brief list of what we're trying to achieve with the docs would be nice
 309 [21:13] <mdke> j1mc: could be, I know he has that in mind often
 310 [21:13] <j1mc> i think that setting up "requirements" of some sort would be helpful in deciding what syntax to use...
 311 [21:13] <philbull> ah, yes
 312 [21:14] <philbull> j1mc: who are we upstream of?
 313 [21:14] <j1mc> that way we can lay out what is important to us and see which platform best meets our needs.
 314 [21:14] <j1mc> philbull: OEM's who redistribute ubuntu.
 315 [21:14] <mdke> philbull: Ubuntu gets customised by quite a few distributors
 316 [21:14] <philbull> who in particular?
 317 [21:14] <mdke> dell?
 318 [21:14] <j1mc> dell
 319 [21:14] <j1mc> system76
 320 [21:14] <nixternal> system76
 321 [21:14] <nixternal> zareason
 322 [21:15] <j1mc> i'm not sure who all else
 323 [21:15] <nixternal> and quite a few more
 324 [21:15] <philbull> do we have contacts with these people? (for docs, in particular)
 325 [21:15] <mdke> various netbook providers maybe
 326 [21:15] <mdke> philbull: I think Kyle is in charge of that side of things in Canonical's OEM team
 327 [21:15] <j1mc> philbull: i'm sure that kyle does
 328 [21:17] <mdke> j1mc: your point about syntax could be remedied by drafting a "MigrationToMallard" spec which sets out the different things that Mallard would need to be able to do to suit our needs
 329 [21:17] <j1mc> i'm not familiar with writing a requirements document, though
 330 [21:17] <j1mc> mdke: exactly
 331 [21:18] <j1mc> mdke: one thing that hasn't reall come up yet with regards to mallard are the server docs.
 332 [21:18] <mdke> that would be part and parcel of trying and testing Mallard out
 333 [21:18] <j1mc> we need to keep their requirements in mind, too
 334 [21:18] <j1mc> yeah - just mentioning it as i don't think it had been mentioned before
 335 [21:18] <mdke> j1mc: it isn't essential that the server guide migrates.
 336 [21:18] <j1mc> mdke: yes.
 337 [21:18] <mdke> personally it hadn't occurred to me that the server guide would move away from docbook
 338 [21:19] <mdke> it's a self contained guide so Mallard's aims don't necessarily apply
 339 [21:19] <j1mc> mdke: sorry... i misread what you had said.
 340 [21:20] <j1mc> server guide could probably stay on docbook, though i'm not as familiar with it.
 341 [21:20] <j1mc> it is the first thing i remove when i go to set up xubuntu docs. :)
 342 [21:20] <mdke> heh
 343 [21:20] <mdke> so, how about this by way of actions
 344 [21:21] <j1mc> so for an action item regarding the requirements doc -
 345 [21:21] <dhillon-v10> j1mc: one quick question: the server guide isn't going to be removed from ubuntu-docs right ?
 346 [21:21] <mdke> [ACTION] as part of testing Mallard, a spec to be drafted setting out what Mallard needs to do for us
 347 [21:21] <mdke> [ACTION]
 348 [21:21] <mdke> whoops
 349 [21:21] <j1mc> mdke: [/ACTION]  :-P
 350 [21:21] <mdke> [ACTION] team to prepare a document setting out aims of writing desktop documentation including Topic based help
 351 [21:22] <mdke> [ACTION] general resolve to update style guide to continue :)
 352 [21:22] <j1mc> mdke: i would draft it a bit more broadly...  yeah.  not just focused on what mallard needs to do for us, but what we require for a doc syntax.
 353 [21:22] <j1mc> s/for/from
 354 [21:22] <mdke> j1mc: sounds good
 355 [21:23] <j1mc> moving on?
 356 [21:23] <mdke> moving on :)
 357 [21:23] <mdke> D"What should we do about screenshots?"
 358 [21:23] <j1mc> dhillon-v10: sorry... no, the serverguide WILL remain in ubuntu docs
 359 [21:23] <j1mc> we aren't going to remove it
 360 [21:23] <j1mc> mdke: i like your suggestion of mostly using screenshots that don't feature text
 361 [21:24] <mdke> my opinion on this remains the same - the value of adding screenshots without text I can see, but for screenshots without text, it would be a big logistical exercise to gather translated screenshots and we'd decrease the amount of completely translated docs we have
 362 [21:25] <mdke> as there would be bound to be screenshots that don't get translated
 363 [21:25] <mdke> taking good screenshots isn't so easy, extrapolate that over 50 languages and we are in trouble
 364 [21:25] <j1mc> mdke: i've been looking over the google chrome help, and in most cases they take the approach of text-less icons when using images.
 365 [21:25] <mdke> so yeah, I'm +1 on a policy for textless icons
 366 [21:25] <j1mc> here's an interesting page, though: http://www.google.com/support/chrome/bin/answer.py?hl=es&answer=95606
 367 [21:26] <mdke> it would be awesome to be able to use icons that adopt the theme that the user reading the help is using
 368 [21:26] <mdke> dunno if that is possible though
 369 [21:26] <mdke> j1mc: heh
 370 [21:26] <j1mc> mdke: i wouldn't think so
 371 [21:26] <mdke> anything is possible!
 372 [21:27] <j1mc> hehe - ok, we'll aim for that for lucid+4 :)
 373 [21:27] <mdke> I'll maybe just file a bug on yelp
 374 [21:27] <mdke> :p
 375 [21:27] <mdke> what do others think about this issue?
 376 [21:29] <j1mc> mdke: i think using a few images that feature text is ok if they are limited in use and will particularly hep the user.
 377 [21:29] <mdke> would we just liaise with the translators through the mailing list and undertake to upload translated images?
 378 [21:29] <j1mc> nixternal: ping ^^^
 379 [21:30] <j1mc> mdke: yeah, i supposed we would want to coordinate well with the translation team.  we'd have to provide really clear instructions on how to take the screenshot in the same way.
 380 [21:30] <j1mc> at least, i think we would.
 381 [21:31] <nixternal> I always wondered about translated images/screenshots myself
 382 [21:31] <mdke> we would yeah. problem is I'm fairly sure that we wouldn't get as many translated screenshots as we do translated docs - Rosetta lowers the barrier so much
 383 [21:32] <j1mc> mdke: in certain cases, i don't think having an untranslated screenshot is so bad.
 384 [21:32] <j1mc> if it isn't anything too specific - as long as it guides the user well enough.
 385 [21:32] <j1mc> they can match things up with their eyes.
 386 [21:33] <j1mc> but generally, i do strongly prefer images w/o text where possible.
 387 [21:33] <mdke> it's not so professional though, as your google chrome page shows
 388 [21:33] <j1mc> mdke: yeah.
 389 [21:34] <mdke> I would still prefer a textless images policy myself. philbull - any thoughts?
 390 [21:34] <philbull> images make the docs much more user friendly
 391 [21:35] <philbull> my connection dropped... did we discuss the issue of people confusing images for the real GUI?
 392 [21:35] <mdke> no, we were talking about what the consequences are if (as I think will happen) certain languages have translated docs but not translated images
 393 [21:36] <philbull> I agree with j1mc, something is better than nothing in most cases
 394 [21:36] <philbull> it's not very professional to have untranslated images, but I don't think that that's a strong enough reason not to use images with text in
 395 [21:37] <philbull> we should just try harder with the translation
 396 [21:37] <philbull> it's a pretty easy way of contributing
 397 [21:37] <philbull> (getting people to send in translated screenshots)
 398 [21:37] <mdke> we can try really hard, but because Rosetta is so easy for translators, the screenshot translation will simply not be as comprehensive as the xml
 399 [21:37] <j1mc> i wonder if there is any way to automate screenshots.
 400 [21:38] <mdke> plus we'll have to take quite a bit of time uploading them all
 401 [21:38] <mdke> and the branch will get huge too
 402 [21:38] <j1mc> like, en_bg *take screenshot*... switch to de *screenshot*... switch to fr *screenshot*...
 403 [21:38] <philbull> I think we can get around all this, if we're smart about it
 404 [21:38] <j1mc> mdke: yeah, branch size would be an issue
 405 [21:38] <philbull> j1mc: I thought about that, but it would be a massive burden on us
 406 [21:39] <philbull> uploading doesn't need to take a long time
 407 [21:39] <philbull> maybe we can do a trial run, with just a few images?
 408 [21:40] <j1mc> i say that we use textless images unless we get team approval for something specific.
 409 [21:40] <j1mc> even in those cases, we should reach out to the translators
 410 [21:40] <philbull> how does this sit with the install CD space limitations?
 411 [21:40] <j1mc> make sure they are aware of the issues.
 412 [21:41] <mdke> philbull: probably wouldn't be an issue - we could split the images out into language packs just like the xml. But it would increase the size of language packs a bit so they might not ship as many on the cd as they do now
 413 [21:41] <humphreybc> The manual will have localized screenshots you guys could use.
 414 [21:41] <philbull> humphreybc: how are you handling the translation of the screenshots?
 415 [21:42] <humphreybc> We're just going to do it manually. We've got enough manpower to basically get the translators to take screenshots as well. Obviously this is the plan, we haven't started it yet so it may all go haywire but I think we should be okay.
 416 [21:43] <humphreybc> We do have to watch how many screenshots we have due to size, but I love screenshots - as they say, a picture is worth a thousand words!
 417 [21:44] <humphreybc> It would be groovy if we could have a screenshot library that we can both use
 418 [21:44] <humphreybc> to save space
 419 [21:45] <mdke> yeah
 420 [21:45] <mdke> we'll need some guidelines for taking useful screenshots too
 421 [21:45] <mdke> to avoid the confusion with the UI issue that philbull mentioned
 422 [21:46] <j1mc> hey all, fwiw, i won a copy of a program called "screensteps" in a contest last year, but couldn't use it because they didn't have a linux version. a guy from the software company wrote me this week to let me know that they have a test version for linux.
 423 [21:46] <j1mc> of course it is propriatary: http://www.google.com/support/chrome/bin/answer.py?hl=es&answer=95606
 424 [21:46] <j1mc> ah, crap
 425 [21:46] <j1mc> sorry, wrong link
 426 [21:46] <humphreybc> sorry about that, laptop just ran out of juice as i plugged it in!
 427 [21:46] <mdke> there is an old page here that could be useful - https://wiki.ubuntu.com/TakingScreenshots
 428 [21:47] <humphreybc> what did I miss?
 429 [21:47] <mdke> 21:46:36 < j1mc> hey all, fwiw, i won a copy of a program called "screensteps" in a contest last year, but couldn't use it because they didn't have a linux version. a guy from the  software company wrote me this week to let me know that they have a test version for linux.
 430 [21:47] <j1mc> http://www.bluemangolearning.com/blog/2010/01/experimental-screensteps-for-linux-beta/
 431 [21:48] <j1mc> i probably won't use it, as it is proprietary, but i think it speaks to the fact that it would be awesome if we had more apps like this for linux... FLOSS ones, that is.
 432 [21:48] <j1mc> a bit off topic, i know...
 433 [21:49] <mdke> ok, let's try and pull the strings together here
 434 [21:49] <mdke> j1mc's proposal seems sane to me, i.e. that we have a textless policy unless there is team approval for something specific
 435 [21:50] <mdke> if we're going to start using screenshots, text or not, I think we should pull together some guidelines on how to take good ones
 436 [21:50] <humphreybc> What do you think about a shared screenshots package?
 437 [21:50] <mdke> package as in deb package?
 438 [21:50] <humphreybc> yes, in the repos
 439 [21:51] <nixternal> mdke: kde has a screenshots policy that has worked, and I thought we used one from gnome a long time ago, like in the 5.04 to 6.06 era
 440 [21:51] <mdke> what would that be used for?
 441 [21:51] <humphreybc> Oh wait are you thinking of including screenshots in yelp or the online docs?
 442 [21:51] <humphreybc> Sorry I missed a fair chunk of the conversation earlier
 443 [21:51] <mdke> humphreybc: we're talking about the system docs right now, which are the same as you see on help.ubuntu.com
 444 [21:51] <mdke> the wiki already uses quite a few screenshots
 445 [21:52] <humphreybc> if hypothetically the manual was included on the CD, it would be silly for us to have screenshots in the manual and you guys to have duplicates in yelp of the same stuff
 446 [21:52] <humphreybc> so a shared screenshot package/database/library call it what you will, would make sense?
 447 [21:52] <mdke> how would the manual use such screenshots? Isn't it intended to be in a pdf?
 448 [21:53] <mdke> but anyway I can't conceive of a world where Ubuntu includes two separate help resources on the CD
 449 [21:53] <humphreybc> It sure is. That would be something that would need to be investigated - perhaps it could somehow be built... oh wait that would require latex installed.
 450 [21:53] <mdke> images in pdfs need to be part of the pdf itself, afaik
 451 [21:54] <humphreybc> well many people couldn't conceive a world where machines build cars, but it happened :)
 452 [21:54] <mdke> that's a different type of conceiving
 453 [21:54] <humphreybc> Either way, I am certain that the screenshots from the manual project could be useful
 454 [21:54] <mdke> obviously, it's technically possible
 455 [21:54] <humphreybc> Especially seeing as they're localized
 456 [21:54] <humphreybc> (or, rather will be)
 457 [21:54] <mdke> yes, reusing good material is clearly a good idea
 458 [21:55] <humphreybc> We'll just have to see how we go. Getting a whole heap of localized screenshots in 30 languages is going to be tough
 459 [21:55] <mdke> yeah, that's my feeling too
 460 [21:55] <humphreybc> Yeah I've always known that. It might not happen in time for Lucid
 461 [21:56] <humphreybc> It's just one of those wait and see things
 462 [21:56] <mdke> ok, let's move on
 463 [21:57] <mdke> don't think we resolved this issue but let's defer to the list in the interest of finishing the meeting
 464 [21:57] <mdke> last item is:
 465 [21:57] <mdke> Screencasts team up for adoption
 466 [21:57] <mdke> popey: around?
 467 [21:57] <humphreybc> I think he said he couldn't make it, mdke
 468 [21:57] <mdke> yeah, but his session may have finished by now
 469 [21:58] <mdke> let's see
 470 [21:58] <mdke> ah, looks like someone else took over his session so maybe he isn't around at all
 471 [21:58] <mdke> ok, deferred to the next meeting :)
 472 [21:59] <mdke> thanks everyone and we'll follow up on the list with the various action items
 473 [21:59] <humphreybc> cool, enjoy the rest of your weekend matt
 474 [21:59] <j1mc> mdke: it's been two hours - i can follow-up about xubuntu docs at a later time.
 475 [21:59] <mdke> oh sorry, I didn't see that extra item
 476 [22:00] <j1mc> i just want to see about being able to test out an html build of the docs relatively early in the process.
 477 [22:00] <mdke> j1mc: up to you
 478 [22:00] <mdke> j1mc: what's the current status?
 479 [22:00] <j1mc> i've got some time to look at things this weekend, but i think i've got a decent idea of what i need to do
 480 [22:01] <j1mc> mdke: i've switched all of the docs to use a xubuntu-menus-C entity file
 481 [22:01] <j1mc> instead of gnome-menus-C
 482 [22:01] <j1mc> and modified the docs to validate against that
 483 22:01:39 < j1mc> but other than that, they still are ubuntu-specific
 484 22:02:01 < j1mc> still, i'd like to get an html build ready within about 2 weeks.
 485 22:02:20 < mdke> ok, I'm happy to help with that
 486 22:02:32 < j1mc> i am more experienced with things now, but will surely have some questions for you.
 487 22:02:40 < mdke> no problem
 488 22:02:45 < j1mc> thanks, mdke
 489 22:03:06 < mdke> no worries - let's call the meeting closed :)