=== itnet7 is now known as itnet7_meetup === KatieKitty is now known as KatieOffline === itnet7_meetup is now known as itnet7|meetup === itnet7|meetup is now known as itnet7 === v is now known as vorian === vish is now known as mac_v === mac_v is now known as vish === KatieOffline is now known as KatieKitty === nigel_nb is now known as Guest58748 === nigelbabu is now known as Guest19591 === KatieKitty is now known as KatieOffline === KatieOffline is now known as KatieKitty === KatieKitty is now known as KatieOffline === KatieOffline is now known as KatieKitty === KatieKitty is now known as KatieOffline === KatieOffline is now known as KatieKitty === KatieKitty is now known as KatieOffline === KatieOffline is now known as KatieKitty === KatieKitty is now known as KatieOffline === nigel_nb is now known as Guest97501 === nigel_nb is now known as Guest36386 === KatieOffline is now known as KatieKitty === KatieKitty is now known as KatieOffline === KatieOffline is now known as KatieKitty === nigel_nb is now known as Guest70547 === Nafallo_ is now known as Nafallo === KatieKitty is now known as KatieOffline === KatieOffline is now known as KatieKitty === yofel_ is now known as yofel [20:00] hi all [20:00] hi j1mc [20:00] hey mdke [20:00] who else do we have for the ubuntu-doc meeting? [20:01] * j1mc looks around [20:02] yo yo [20:04] I wish there was a way to put everything but a single channel on mute easily [20:04] hey nixternal [20:04] how goes it mr. east? [20:04] hello [20:05] nice to see so much activity on kubuntu-docs lately [20:05] son just woke up from nap so i don't know how much i'll be here [20:05] nixternal: good thanks, you? [20:05] I guess I am doing good...a bit busy but good [20:05] you suing the pants off of people over there? :D === mcas_ is now known as mcas [20:05] hey jjesse [20:05] oh wait, only in the US do they sue the pants off of people [20:06] :p [20:06] nixternal: yes, more or less. A certain amount of getting sued as well [20:06] hi all, just got here :) [20:06] oh, so they keep it interesting [20:06] hiya mdke [20:06] hi dhillon-v10 [20:06] j1mc: hi :) [20:06] any sign of Phil? [20:07] j1mc: we have flourish coming up, we should talk to them and see if we can get a "documentation" hack-a-thon or something going there [20:07] hi guys [20:07] there he is... :) [20:07] heh, right as you asked about phil :) [20:07] hey philbull [20:07] great, hi phil [20:07] philbull: hi :) [20:07] hey, I'm on a crappy Internet connection [20:07] hence the lateness [20:07] no worries, shall we get started? [20:08] sure [20:08] shall we use the bot? [20:08] i guess so [20:08] i'm not so adept at the bot - i should probably read up on it. [20:08] let's give it a shot [20:08] #startmeeting [20:08] [] [20:09] bot isn't here :) [20:09] mdke: :) [20:09] oh well, agenda is here: https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda [20:09] well that would explain everything then :) [20:09] first item: Is moving to Mallard for the system help viable? [20:09] discuss :) [20:10] I'm pretty interested in whether there will be any chance of kde adoption [20:10] not yet, but possibly in the future [20:10] I think that will be important for us. nixternal- any idea? [20:10] mdke: don't know for sure, most of the docs. in kde just got updated [20:10] i'm fine with writing with it, and it is fine for individual help files. i have some concerns about widespread adoption. [20:10] shaunm, myself, and burk from kde will work on it in the future [20:11] hi everone, sorry i'm a bit late. it's 9am on sunday morning over here! [20:11] nixternal: and me :) [20:11] nixternal: will you go to the help summit that Shaun has organised? [20:11] yes, since it just a few minutes from my house :) [20:11] hey humphreybc [20:11] nixternal and i are both in chicago, where the help summit will be held [20:11] awesome, that will be a good chance to discuss it [20:11] j1mc: what are your concerns? [20:11] you've been trying it for xfce, right? [20:11] well, for example... the "administrative tasks" page gets linked to a ton of times from within ubuntu docs. [20:12] with the auto linking... there would be a lot of links at the bottom of the page linking to related pages. [20:12] that is just one thing that comes to mind. [20:13] I suspect there would be an element of rewriting to take account of things like that, no? [20:13] j1mc: possible to have something like a page: "Resources" mentioning all those links [20:13] mdke: yes - it is just a concern, that's all. [20:13] * mdke nods [20:13] has it taken off with xfce? [20:13] i am trying to make chicago as well [20:13] we can talk to shaun about this [20:13] also, the linking is designed to be from all within the same folder, if i understand correctly. [20:13] jjesse: awesome [20:14] Mallard is still technically in development [20:14] philbull: understood. shaun's doing some cool stuff [20:14] i would just have concerns about requiring the docs to be all in the same folder if things were to scale up. [20:15] can we symlink? [20:15] 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 [20:15] yes [20:15] oops, lil late, hi people. Been helping with user days. :) [20:15] philbull: i think symlinking would get messy. [20:15] welcome, starcraftman [20:16] j1mc: can we do some build magic then? [20:16] philbull: what do you have in mind? [20:16] keep the files in separate dirs in bzr and just put them into the same one when we install the package? [20:17] oh yeah, of course that's doable, if it's the right solution [20:17] it's not as neat as supporting subdirs, i guess [20:17] but wouldn't the top level topics be mallard guide files anyway? [20:17] so they could have their own folder [20:17] and then be brought together by the index [20:17] yes, that's what i was thinking [20:18] i wonder if you can link to things in other folders... is it just that the auto-linking doesn't work across other folders? [20:19] again, we can ask for a modification to the Mallard implementation [20:19] 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). [20:19] I'm not opposed to this... just want to make sure it will work and that it will scale well. [20:19] 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? [20:19] the GNOME user guide will be the acid test [20:19] it'll be huge, much bigger than ubuntu-docs [20:19] mdke: i think adoption for lucid is premature [20:19] +1 [20:20] it doesn't stop us from trying to migrate for fun and giving feedback to upstream to help refine the project [20:20] I also think that 10.04 is a bad time. [20:20] we need to be looking into it now, though [20:20] Definitely try testing it in another branch now though [20:20] I think experimenting is a good idea [20:20] actually, I think we should keep trying things so that we can be involved in the development of the project [20:20] So everyone agrees that a change will have to come this year at some point, most likely in 10.10? [20:21] shaun and i will both be attending that writersua conference. it's just too bad that it's immediately after the help summit. [20:21] humphreybc: I think that's a bit early to say [20:21] (need to skip out for 10 mins, back soon) [20:21] humphreybc: we'll keep our eye on upstream and see whether kde get interested too [20:21] what are the kde docs like? sorry i've never really used kde [20:21] but frankly Gnome will be moving, and so for ubuntu-docs, moving is more or less a slamdunk decision [20:22] 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 [20:22] dhillon-v10: the same is true of Gnome [20:22] mdke: i still wonder - if gnome is finding that it isn't scaling well... what would happen [20:22] mdke: really ?? === KatieKitty is now known as KatieOffline [20:22] dhillon-v10: totally. they see Mallard as a way of getting people excited about contributing again. They are planning a complete rewrite [20:22] ... we could split off from using upstream docs and write our own stuff? [20:22] j1mc: indeed [20:23] 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 [20:23] nixternal: :) true [20:23] humphreybc: yes, we could. But that's not really what Ubuntu is about. [20:23] humphreybc: waaaaaaay to much work,first writing them, then updating and all that good stuff :) [20:23] *too [20:24] 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? [20:24] indeed. but as Ubuntu gets bigger, at some point that might become a necessity. Probably not this year though :P [20:24] I think a testing branch is a great idea. [20:24] 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 [20:25] mdke: sure :) [20:25] humphreybc: I don't really understand. Ubuntu is built out of upstreams, it's only possible because of the reuse of upstream work [20:25] humphreybc: the same reasoning is perfectly valid for documentation [20:25] why would we start from scratch if material can be reused? [20:25] mdke: okay fair enough [20:25] ok, let's try and summarise some action points here [20:26] [ACTION] - ubuntu-doc to play around with a Mallard testing branch to test scalability and migration [20:26] [ACTION] - kubuntu-docs to discuss with Shaun in Chicago possibility of KDE migration [20:27] [ACTION] - general liaising with upstream and continued reevaluation with a view to possible migration in lucid+1 or whenever ready [20:27] does that sound sensible? [20:27] nixternal: shaun was also interested in getting together briefly sometime before the summit. [20:27] j1mc: I am open [20:27] mdke: i think that sounds perfectly reasonable [20:27] mdke: yep sounds rad [20:28] ok, any other comments on Mallard? [20:28] not from me for now. [20:28] negative [20:29] ok, next topic [20:29] Improving the New to Ubuntu docs - [[DocumentationTeam/Ideas/NewToUbuntu|spec here for discussion]] [20:29] I've sketched out a plan for the new "newtoubuntu.xml" in ubuntu-docs on that wiki page [20:29] I've bashed out two or three quick sections in the bzr branch too so that people can see what I had in mind [20:30] * j1mc looks at the page [20:30] any comments on the spec or initial material are very welcome [20:31] 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 :) [20:31] * humphreybc also looks [20:31] 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 [20:31] although it might be faster starting up an individual document [20:31] mdke: yaeah working on that with Shaun :) [20:31] mdke: that table of contents looks very similar to the first few chapters of the manual [20:32] *yeah [20:32] humphreybc: the whole manual looks pretty similar to our docs :) [20:32] mdke: lol [20:32] 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 [20:32] but yeah, it's not innovative thinking or anything, just common sense, I hope [20:33] it seems like a good start. i would have to think about it a bit more to really offer any suggestions at this point. [20:33] 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? [20:34] its been around for years and gets installed with the ubuntu-docs package [20:34] 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 [20:34] okay so very short, like < 10 pages short? [20:34] would it use yelp or a standalone PDF? [20:35] maybe eight pages with about 30 words in each page [20:35] yes, it's for the system documentation, so will be part of yelp [20:35] gotcha [20:35] 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. [20:35] the manual isn't on the agenda . . . i'd probably rather not discuss it at this point. [20:35] 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 [20:35] AtomicSpark: that would tend to be my feeling too [20:35] 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 [20:36] humphreybc: ok [20:36] humphreybc: have you seen the screenshot lower down the page? That's the sort of detail we're talking about [20:36] for one of the topics [20:36] if you have a look at the manual TOC, which will be more detailed for sure, https://wiki.ubuntu.com/ubuntu-manual/TableOfContents [20:37] humphreybc: https://wiki.ubuntu.com/DocumentationTeam/Ideas/NewToUbuntu?action=AttachFile&do=get&target=adding-applications.png [20:37] 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 [20:37] that would be chapter 5 [20:37] ah so it's *very* brief ;) [20:37] well, that's probably more than 30 words, but yes. [20:38] we have other documents covering all of those subjects in more detail [20:38] which are linked to [20:38] mdke: you just answered my question, thanks :) [20:38] 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 [20:39] 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 [20:39] Of course, we obviously have rather nice introduction paragraphs etc for each of our chapters that you are welcome to use [20:39] anyway, if anyone has further comments on the spec, then feel free to send them to the list [20:40] unless anyone has immediate comments, let's move on [20:40] sounds good. :) [20:40] I have one comment [20:40] too many notes! [20:40] in the screenshot? [20:40] yes [20:41] that could easily use something else, like a bullet list [20:41] sure, it's just a minor point [20:41] I was carried away by Kyle's frenzied call for images [20:41] he he [20:41] where is this sample page? link? [20:42] j1mc: it's the really long link above [20:42] I've done the Welcome and Getting Help sections too [20:42] are the people working on the New to Ubuntu stuff interacting with real users in some way? [20:42] mdke: which bzr branch are the examples in? lucid? [20:43] AtomicSpark: yep - newtoubuntu/C/newtoubuntu.xml [20:43] philbull: not so far - what suggestions would you have? [20:43] I'm always amazed when I watch new users use Ubuntu [20:43] this arises in relation to the "Common Questions" things in yelp too [20:43] they get stuck on things that you'd never believe [20:44] it's because we're so familiar with this stuff, but it's completely new to them [20:44] I believe that the design team has been doing some user testing that we might be able to rely on [20:44] sure, but are they opening it up? [20:44] Perhaps we could contact them and ask for some feedback or whether we can get access to it [20:44] philbull: we won't know unless we ask I guess [20:44] I asked mpt about getting user testing videos a few months back [20:45] what did he say? [20:45] as far as I remember, he wasn't keen [20:45] I'll have to go back through my email though [20:45] I know that his team is interested in helping with docs though - I bet they just haven't had time yet [20:45] I think they might have been able to give us text reports of user testing [20:45] so if we approach them, they *must* have some way they can help [20:45] not really the same as seeing it for yourself though [20:46] we can all do some limited testing of our own [20:46] I've used my girlfriend and some friends as guinea pigs [20:47] 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 [20:47] :) [20:47] dhillon-v10: i think shaunm was looking into integrating with telepathy for that somehow, too. [20:47] I'd be pretty happy to trust the design team's evaluation of their user testing for our purposes [20:48] mdke, j1mc: so do you guys think its a good idea [20:48] mdke: could you rephrase? i'm not sure what you mean. [20:49] 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 [20:49] I think their analysis of them would be pretty useful, frankly [20:49] mdke: ah, ok... so you are saying that just seeing their analysis would be... yeah, useful. [20:49] especially since we have limited time to do our own user testing [20:49] right [20:49] they are experts at user testing, after all [20:49] yup [20:50] dhillon-v10: I'm not sure, I'd like to think about it a bit more [20:51] anyway, as an action, how about this: [20:51] [ACTION] mdke to contact design team to get their input into what subjects could be covered and where users have common problems [20:52] sounds greta [20:52] great :) [20:52] [ACTION] any other feedback on NewToUbuntu to the mailing list [20:52] next item ;) [20:52] Writing an installation guide (The Ubuntu Manual has content for this that can be used) [20:52] mdke: I have something down, so can that be used [20:52] philbull: you want to sum up status? [20:52] yes [20:53] err, we didn;t get very far [20:53] everyone was too busy [20:53] are those who were interested still around? [20:53] some are, I think [20:53] o/ [20:53] I don't think that having the smaller focused team worked too well [20:54] at the end of the day, we're all volunteers who need to work around other stuff [20:54] What do we want in an installation guide? Installing from a Live CD and what the available options do? [20:55] the idea was to get people from Windows to Ubuntu in the least painful way [20:55] we already have a detailed installation *manual* [20:55] we don;t want to document every possible installation route [20:55] do we? [20:55] yes, the Debian installation guide [20:56] ah, but that only covers the alternate cd, not the desktop cd, asaik [20:56] *afaik [20:56] yes [20:56] but do we need a detailed manual for the GUI installer? [20:56] AtomicSpark: there is this spec about the planned guide - https://wiki.ubuntu.com/Specs/KarmicInstallationGuide [20:56] or are we better off doing a user-assistance job? [20:57] yeah I agree. The partitioning is a tricky bit but there's no point talking people through selecting their time zone [20:57] i think an installation "guide" is appropriate here. having "help" topics for problems would make sense, though. [20:58] j1mc: yes, this is a situation where having something that could be printed off is a good idea [20:58] it's difficult to know exactly what to cover [20:59] From my experince with other users, I'd say that partitioning is a big hurdle. [20:59] I think the planning for the guide was done pretty well and the table of contents on the spec looks quite good [20:59] philbull: how far did you get with outlining, drafting and writing? [20:59] And how exactly dual booting works. [20:59] with the writing, not very far [21:00] all of the other stuff is on the wiki [21:00] so, what are the most common problems that people deal with when installing? [21:01] dual booting and partitioning, definitely [21:01] but also post-install stuff like hardware [21:01] problems with the bootloader too [21:02] problems with the bootloader are definitely scary for new users. [21:02] so, I think there is a case for providing a brief, basic walkthrough [21:02] lots of pictures etc [21:02] philbull: what approach could be taken to revive the team around this? [21:03] then separate, focused how-tos (for partitioning/dual-booting) and troubleshooting material [21:03] that seems like the biggest issue... getting people involved again. [21:03] Hardware and drivers. Internet stuff like Flash and Java (although we have topics that cover this). [21:03] I think getting the doc into the branch with a structure might help people get involved [21:03] people in the Manual Team might be interested [21:04] I want to write this in plain text first, before we do any markup [21:04] ah [21:04] that should really lower the bar to contribution [21:04] I can mark stuff up in about an afternoon [21:04] there's no point other people worrying about it, the content is by far the most important part [21:05] so there won't be the usual ubuntu-doc QA structure of patch + review by ~ubuntu-core-doc member [21:05] * j1mc nods [21:05] AtomicSpark: we have to be careful with what constitutes "installation" and what is "New to ubuntu" [21:05] mdke: not initially [21:05] True. I was just throwing things up there. ;) [21:05] of course, someone (probably me) edits together a coherent draft [21:05] right [21:05] the peer review can be continuous, but informal [21:06] 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 [21:06] sure, that would be a very good idea [21:06] we need to make a firm spec for the installation guide, though [21:06] different to the existing one? [21:06] maybe modify it [21:07] we have to be clear on how it interacts with the New to Ubuntu docs [21:07] I'd suggest modifying rather than starting again, it looks in decent shape [21:07] true [21:07] people are always tempted to start explaining how to add applications [21:07] yes, that sort of thing is clearly not installing Ubuntu [21:07] the IG should be short and sweet, installation only [21:08] agreed [21:08] so, maybe we should discuss this more on-list [21:08] there should be some really fun potential for new contributors here [21:08] some nice, difficult problems for people to explain in a user-friendly way [21:09] will you take it forward on the list then? [21:10] sure [21:10] cool [21:10] shall we move on? [21:10] [ACTION] philbull to raise the installation-guide on the list and plan future action [21:10] yep, next topic [21:10] Setting out a Requirements document to guide our efforts [21:10] this is an interesting idea [21:11] sort of like a manifesto? [21:11] I think what Kyle was saying was basically this [21:11] Discussions on the list sometimes get unfocused because of a lack of understanding about what the team does [21:12] and what it's objectives are [21:12] 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 [21:12] mdke: i think it also takes into consideration our own roles as "upstream" doc providers. [21:13] calling it a "requirements document" seems a bit rigid to me, I don't think we really have such things [21:13] which i'm not so sure we had really considered so much before [21:13] I think having a brief list of what we're trying to achieve with the docs would be nice [21:13] j1mc: could be, I know he has that in mind often [21:13] i think that setting up "requirements" of some sort would be helpful in deciding what syntax to use... [21:13] ah, yes [21:14] j1mc: who are we upstream of? [21:14] that way we can lay out what is important to us and see which platform best meets our needs. [21:14] philbull: OEM's who redistribute ubuntu. [21:14] philbull: Ubuntu gets customised by quite a few distributors [21:14] who in particular? [21:14] dell? [21:14] dell [21:14] system76 [21:14] system76 [21:14] zareason [21:15] i'm not sure who all else [21:15] and quite a few more [21:15] do we have contacts with these people? (for docs, in particular) [21:15] various netbook providers maybe [21:15] philbull: I think Kyle is in charge of that side of things in Canonical's OEM team [21:15] philbull: i'm sure that kyle does [21:17] 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 [21:17] i'm not familiar with writing a requirements document, though [21:17] mdke: exactly [21:18] mdke: one thing that hasn't reall come up yet with regards to mallard are the server docs. [21:18] that would be part and parcel of trying and testing Mallard out [21:18] we need to keep their requirements in mind, too [21:18] yeah - just mentioning it as i don't think it had been mentioned before [21:18] j1mc: it isn't essential that the server guide migrates. [21:18] mdke: yes. [21:18] personally it hadn't occurred to me that the server guide would move away from docbook [21:19] it's a self contained guide so Mallard's aims don't necessarily apply [21:19] mdke: sorry... i misread what you had said. [21:20] server guide could probably stay on docbook, though i'm not as familiar with it. [21:20] it is the first thing i remove when i go to set up xubuntu docs. :) [21:20] heh [21:20] so, how about this by way of actions [21:21] so for an action item regarding the requirements doc - [21:21] j1mc: one quick question: the server guide isn't going to be removed from ubuntu-docs right ? [21:21] [ACTION] as part of testing Mallard, a spec to be drafted setting out what Mallard needs to do for us [21:21] [ACTION] [21:21] whoops [21:21] mdke: [/ACTION] :-P [21:21] [ACTION] team to prepare a document setting out aims of writing desktop documentation including Topic based help [21:22] [ACTION] general resolve to update style guide to continue :) [21:22] 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. [21:22] s/for/from [21:22] j1mc: sounds good [21:23] moving on? [21:23] moving on :) [21:23] D"What should we do about screenshots?" [21:23] dhillon-v10: sorry... no, the serverguide WILL remain in ubuntu docs [21:23] we aren't going to remove it [21:23] mdke: i like your suggestion of mostly using screenshots that don't feature text [21:24] 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 [21:25] as there would be bound to be screenshots that don't get translated [21:25] taking good screenshots isn't so easy, extrapolate that over 50 languages and we are in trouble [21:25] 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. [21:25] so yeah, I'm +1 on a policy for textless icons [21:25] here's an interesting page, though: http://www.google.com/support/chrome/bin/answer.py?hl=es&answer=95606 [21:26] it would be awesome to be able to use icons that adopt the theme that the user reading the help is using [21:26] dunno if that is possible though [21:26] j1mc: heh [21:26] mdke: i wouldn't think so [21:26] anything is possible! [21:27] hehe - ok, we'll aim for that for lucid+4 :) [21:27]