This is a meeting summary and log for the DocumentationTeam meeting of 23 January 2010.
Agenda
- 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
Summary
- 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
Log
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 :)