This is a meeting summary and log for the DocumentationTeam meeting of 23 January 2010.
- Is moving to Mallard for the system help viable?
Improving the New to Ubuntu docs - spec here for discussion
- Writing an installation guide (The Ubuntu Manual has content for this that can be used)
- Setting out a Requirements document to guide our efforts
- What should we do about screenshots?
- Screencasts team up for adoption
- Xubuntu docs status update
- Is moving to Mallard for the system help viable?
- the team to play around with a Mallard testing branch to test scalability and migration
- kubuntu-docs to discuss with Shaun in Chicago possibility of KDE migration
- general liaising with upstream and continued reevaluation with a view to possible migration in lucid+1 or whenever ready
Improving the New to Ubuntu docs - spec here for discussion
- mdke to contact design team to get their input into what subjects could be covered and where users have common problems
any other feedback on NewToUbuntu to the mailing list
- Writing an installation guide (The Ubuntu Manual has content for this that can be used)
- philbull to raise the installation-guide on the list and plan future action
- Setting out a Requirements document to guide our efforts
- as part of testing Mallard, a spec to be drafted setting out the team needs from syntax
- team to prepare a document setting out aims of writing desktop documentation including topic based help
general resolve to update style guide to continue
- What should we do about screenshots?
- proposal that the team has a policy of using textless screenshots unless there is team approval for something specific to be discussed further on mailing list
some work to be put into developing guidelines for screenshots including Gnome/KDE guidelines and TakingScreenshots
- Screencasts team up for adoption
Deferred to next meeting
- Xubuntu docs status update
- j1mc to work with mdke to get docs building to HTML
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 :)