January2011
Differences between revisions 6 and 7
|
Size: 41803
Comment: ## page was copied from MeetingLogs/DocTeam/January2010
|
← Revision 7 as of 2011-03-07 15:38:05 ⇥
Size: 18445
Comment: Added last docs team meeting log
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 6: | Line 6: |
| * Is moving to Mallard for the system help viable? * Improving the New to Ubuntu docs - [[DocumentationTeam/Ideas/NewToUbuntu|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 |
* ... |
| Line 16: | Line 10: |
| * 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 - [[DocumentationTeam/Ideas/NewToUbuntu|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 |
* ... |
| Line 40: | Line 15: |
| [20:07] <mdke> no worries, shall we get started? [20:08] <philbull> sure [20:08] <mdke> shall we use the bot? [20:08] <philbull> i guess so [20:08] <j1mc> i'm not so adept at the bot - i should probably read up on it. [20:08] <mdke> let's give it a shot [20:08] <mdke> #startmeeting [20:08] <nixternal> [] [20:09] <mdke> bot isn't here :) [20:09] <dhillon-v10> mdke: :) [20:09] <mdke> oh well, agenda is here: https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda [20:09] <nixternal> well that would explain everything then :) [20:09] <mdke> first item: Is moving to Mallard for the system help viable? [20:09] <mdke> discuss :) [20:10] <mdke> I'm pretty interested in whether there will be any chance of kde adoption [20:10] <nixternal> not yet, but possibly in the future [20:10] <mdke> I think that will be important for us. nixternal- any idea? [20:10] <dhillon-v10> mdke: don't know for sure, most of the docs. in kde just got updated [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:10] <nixternal> shaunm, myself, and burk from kde will work on it in the future [20:11] <humphreybc> hi everone, sorry i'm a bit late. it's 9am on sunday morning over here! [20:11] <dhillon-v10> nixternal: and me :) [20:11] <mdke> nixternal: will you go to the help summit that Shaun has organised? [20:11] <nixternal> yes, since it just a few minutes from my house :) [20:11] <philbull> hey humphreybc [20:11] <j1mc> nixternal and i are both in chicago, where the help summit will be held [20:11] <mdke> awesome, that will be a good chance to discuss it [20:11] <mdke> j1mc: what are your concerns? [20:11] <mdke> you've been trying it for xfce, right? [20:11] <j1mc> well, for example... the "administrative tasks" page gets linked to a ton of times from within ubuntu docs. [20:12] <j1mc> with the auto linking... there would be a lot of links at the bottom of the page linking to related pages. [20:12] <j1mc> that is just one thing that comes to mind. [20:13] <mdke> I suspect there would be an element of rewriting to take account of things like that, no? [20:13] <dhillon-v10> j1mc: possible to have something like a page: "Resources" mentioning all those links [20:13] <j1mc> mdke: yes - it is just a concern, that's all. [20:13] * mdke nods [20:13] <mdke> has it taken off with xfce? [20:13] <jjesse> i am trying to make chicago as well [20:13] <philbull> we can talk to shaun about this [20:13] <j1mc> also, the linking is designed to be from all within the same folder, if i understand correctly. [20:13] <mdke> jjesse: awesome [20:14] <philbull> Mallard is still technically in development [20:14] <j1mc> philbull: understood. shaun's doing some cool stuff [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. [20:15] <philbull> can we symlink? [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 [20:15] <j1mc> yes [20:15] <starcraftman> oops, lil late, hi people. Been helping with user days. :) [20:15] <j1mc> philbull: i think symlinking would get messy. [20:15] <j1mc> welcome, starcraftman [20:16] <philbull> j1mc: can we do some build magic then? [20:16] <mdke> philbull: what do you have in mind? [20:16] <philbull> keep the files in separate dirs in bzr and just put them into the same one when we install the package? [20:17] <mdke> oh yeah, of course that's doable, if it's the right solution [20:17] <philbull> it's not as neat as supporting subdirs, i guess [20:17] <mdke> but wouldn't the top level topics be mallard guide files anyway? [20:17] <mdke> so they could have their own folder [20:17] <mdke> and then be brought together by the index [20:17] <philbull> yes, that's what i was thinking [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? [20:19] <philbull> again, we can ask for a modification to the Mallard implementation [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). [20:19] <j1mc> I'm not opposed to this... just want to make sure it will work and that it will scale well. [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? [20:19] <philbull> the GNOME user guide will be the acid test [20:19] <philbull> it'll be huge, much bigger than ubuntu-docs [20:19] <j1mc> mdke: i think adoption for lucid is premature [20:19] <philbull> +1 [20:20] <mdke> it doesn't stop us from trying to migrate for fun and giving feedback to upstream to help refine the project [20:20] <humphreybc> I also think that 10.04 is a bad time. [20:20] <philbull> we need to be looking into it now, though [20:20] <humphreybc> Definitely try testing it in another branch now though [20:20] <philbull> I think experimenting is a good idea [20:20] <mdke> actually, I think we should keep trying things so that we can be involved in the development of the project [20:20] <humphreybc> So everyone agrees that a change will have to come this year at some point, most likely in 10.10? [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. [20:21] <mdke> humphreybc: I think that's a bit early to say [20:21] <philbull> (need to skip out for 10 mins, back soon) [20:21] <mdke> humphreybc: we'll keep our eye on upstream and see whether kde get interested too [20:21] <humphreybc> what are the kde docs like? sorry i've never really used kde [20:21] <mdke> but frankly Gnome will be moving, and so for ubuntu-docs, moving is more or less a slamdunk decision [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 [20:22] <mdke> dhillon-v10: the same is true of Gnome [20:22] <j1mc> mdke: i still wonder - if gnome is finding that it isn't scaling well... what would happen [20:22] <dhillon-v10> mdke: really ?? === KatieKitty is now known as KatieOffline [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 [20:22] <humphreybc> ... we could split off from using upstream docs and write our own stuff? [20:22] <mdke> j1mc: indeed [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 [20:23] <dhillon-v10> nixternal: :) true [20:23] <mdke> humphreybc: yes, we could. But that's not really what Ubuntu is about. [20:23] <dhillon-v10> humphreybc: waaaaaaay to much work,first writing them, then updating and all that good stuff :) [20:23] <dhillon-v10> *too [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? [20:24] <humphreybc> indeed. but as Ubuntu gets bigger, at some point that might become a necessity. Probably not this year though :P [20:24] <humphreybc> I think a testing branch is a great idea. [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 [20:25] <dhillon-v10> mdke: sure :) [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 [20:25] <mdke> humphreybc: the same reasoning is perfectly valid for documentation [20:25] <mdke> why would we start from scratch if material can be reused? [20:25] <humphreybc> mdke: okay fair enough [20:25] <mdke> ok, let's try and summarise some action points here [20:26] <mdke> [ACTION] - ubuntu-doc to play around with a Mallard testing branch to test scalability and migration [20:26] <mdke> [ACTION] - kubuntu-docs to discuss with Shaun in Chicago possibility of KDE migration [20:27] <mdke> [ACTION] - general liaising with upstream and continued reevaluation with a view to possible migration in lucid+1 or whenever ready [20:27] <mdke> does that sound sensible? [20:27] <j1mc> nixternal: shaun was also interested in getting together briefly sometime before the summit. [20:27] <nixternal> j1mc: I am open [20:27] <j1mc> mdke: i think that sounds perfectly reasonable [20:27] <humphreybc> mdke: yep sounds rad [20:28] <mdke> ok, any other comments on Mallard? [20:28] <j1mc> not from me for now. [20:28] <humphreybc> negative [20:29] <mdke> ok, next topic [20:29] <mdke> Improving the New to Ubuntu docs - [[DocumentationTeam/Ideas/NewToUbuntu|spec here for discussion]] [20:29] <mdke> I've sketched out a plan for the new "newtoubuntu.xml" in ubuntu-docs on that wiki page [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 [20:30] * j1mc looks at the page [20:30] <mdke> any comments on the spec or initial material are very welcome [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 :) [20:31] * humphreybc also looks [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 [20:31] <mdke> although it might be faster starting up an individual document [20:31] <dhillon-v10> mdke: yaeah working on that with Shaun :) [20:31] <humphreybc> mdke: that table of contents looks very similar to the first few chapters of the manual [20:32] <dhillon-v10> *yeah [20:32] <mdke> humphreybc: the whole manual looks pretty similar to our docs :) [20:32] <dhillon-v10> mdke: lol [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 [20:32] <mdke> but yeah, it's not innovative thinking or anything, just common sense, I hope [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. [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? [20:34] <nixternal> its been around for years and gets installed with the ubuntu-docs package [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 [20:34] <humphreybc> okay so very short, like < 10 pages short? [20:34] <humphreybc> would it use yelp or a standalone PDF? [20:35] <mdke> maybe eight pages with about 30 words in each page [20:35] <mdke> yes, it's for the system documentation, so will be part of yelp [20:35] <humphreybc> gotcha [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. [20:35] <j1mc> the manual isn't on the agenda . . . i'd probably rather not discuss it at this point. [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 [20:35] <mdke> AtomicSpark: that would tend to be my feeling too [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 [20:36] <j1mc> humphreybc: ok [20:36] <mdke> humphreybc: have you seen the screenshot lower down the page? That's the sort of detail we're talking about [20:36] <mdke> for one of the topics [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 [20:37] <mdke> humphreybc: https://wiki.ubuntu.com/DocumentationTeam/Ideas/NewToUbuntu?action=AttachFile&do=get&target=adding-applications.png [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 [20:37] <mdke> that would be chapter 5 [20:37] <humphreybc> ah so it's *very* brief ;) [20:37] <mdke> well, that's probably more than 30 words, but yes. [20:38] <mdke> we have other documents covering all of those subjects in more detail [20:38] <mdke> which are linked to [20:38] <dhillon-v10> mdke: you just answered my question, thanks :) [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 [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 [20:39] <humphreybc> Of course, we obviously have rather nice introduction paragraphs etc for each of our chapters that you are welcome to use [20:39] <mdke> anyway, if anyone has further comments on the spec, then feel free to send them to the list [20:40] <mdke> unless anyone has immediate comments, let's move on [20:40] <j1mc> sounds good. :) [20:40] <philbull> I have one comment [20:40] <philbull> too many notes! [20:40] <mdke> in the screenshot? [20:40] <philbull> yes [20:41] <mdke> that could easily use something else, like a bullet list [20:41] <philbull> sure, it's just a minor point [20:41] <mdke> I was carried away by Kyle's frenzied call for images [20:41] <philbull> he he [20:41] <j1mc> where is this sample page? link? [20:42] <mdke> j1mc: it's the really long link above [20:42] <mdke> I've done the Welcome and Getting Help sections too [20:42] <philbull> are the people working on the New to Ubuntu stuff interacting with real users in some way? [20:42] <AtomicSpark> mdke: which bzr branch are the examples in? lucid? [20:43] <mdke> AtomicSpark: yep - newtoubuntu/C/newtoubuntu.xml [20:43] <mdke> philbull: not so far - what suggestions would you have? [20:43] <philbull> I'm always amazed when I watch new users use Ubuntu [20:43] <mdke> this arises in relation to the "Common Questions" things in yelp too [20:43] <philbull> they get stuck on things that you'd never believe [20:44] <philbull> it's because we're so familiar with this stuff, but it's completely new to them [20:44] <mdke> I believe that the design team has been doing some user testing that we might be able to rely on [20:44] <philbull> sure, but are they opening it up? [20:44] <mdke> Perhaps we could contact them and ask for some feedback or whether we can get access to it [20:44] <mdke> philbull: we won't know unless we ask I guess [20:44] <philbull> I asked mpt about getting user testing videos a few months back [20:45] <mdke> what did he say? [20:45] <philbull> as far as I remember, he wasn't keen [20:45] <philbull> I'll have to go back through my email though [20:45] <mdke> I know that his team is interested in helping with docs though - I bet they just haven't had time yet [20:45] <philbull> I think they might have been able to give us text reports of user testing [20:45] <mdke> so if we approach them, they *must* have some way they can help [20:45] <philbull> not really the same as seeing it for yourself though [20:46] <philbull> we can all do some limited testing of our own [20:46] <philbull> I've used my girlfriend and some friends as guinea pigs [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 [20:47] <dhillon-v10> :) [20:47] <j1mc> dhillon-v10: i think shaunm was looking into integrating with telepathy for that somehow, too. [20:47] <mdke> I'd be pretty happy to trust the design team's evaluation of their user testing for our purposes [20:48] <dhillon-v10> mdke, j1mc: so do you guys think its a good idea [20:48] <j1mc> mdke: could you rephrase? i'm not sure what you mean. [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 [20:49] <mdke> I think their analysis of them would be pretty useful, frankly [20:49] <j1mc> mdke: ah, ok... so you are saying that just seeing their analysis would be... yeah, useful. [20:49] <mdke> especially since we have limited time to do our own user testing [20:49] <j1mc> right [20:49] <mdke> they are experts at user testing, after all [20:49] <j1mc> yup [20:50] <mdke> dhillon-v10: I'm not sure, I'd like to think about it a bit more [20:51] <mdke> anyway, as an action, how about this: [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 [20:52] <j1mc> sounds greta [20:52] <j1mc> great :) [20:52] <mdke> [ACTION] any other feedback on NewToUbuntu to the mailing list [20:52] <mdke> next item ;) [20:52] <mdke> Writing an installation guide (The Ubuntu Manual has content for this that can be used) [20:52] <dhillon-v10> mdke: I have something down, so can that be used [20:52] <mdke> philbull: you want to sum up status? [20:52] <philbull> yes [20:53] <philbull> err, we didn;t get very far [20:53] <philbull> everyone was too busy [20:53] <mdke> are those who were interested still around? [20:53] <philbull> some are, I think [20:53] <dhillon-v10> o/ [20:53] <philbull> I don't think that having the smaller focused team worked too well [20:54] <philbull> at the end of the day, we're all volunteers who need to work around other stuff [20:54] <AtomicSpark> What do we want in an installation guide? Installing from a Live CD and what the available options do? [20:55] <philbull> the idea was to get people from Windows to Ubuntu in the least painful way [20:55] <philbull> we already have a detailed installation *manual* [20:55] <philbull> we don;t want to document every possible installation route [20:55] <mdke> do we? [20:55] <philbull> yes, the Debian installation guide [20:56] <mdke> ah, but that only covers the alternate cd, not the desktop cd, asaik [20:56] <mdke> *afaik [20:56] <philbull> yes [20:56] <philbull> but do we need a detailed manual for the GUI installer? [20:56] <mdke> AtomicSpark: there is this spec about the planned guide - https://wiki.ubuntu.com/Specs/KarmicInstallationGuide [20:56] <philbull> or are we better off doing a user-assistance job? [20:57] <mdke> yeah I agree. The partitioning is a tricky bit but there's no point talking people through selecting their time zone [20:57] <j1mc> i think an installation "guide" is appropriate here. having "help" topics for problems would make sense, though. [20:58] <philbull> j1mc: yes, this is a situation where having something that could be printed off is a good idea [20:58] <philbull> it's difficult to know exactly what to cover [20:59] <AtomicSpark> From my experince with other users, I'd say that partitioning is a big hurdle. [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 [20:59] <j1mc> philbull: how far did you get with outlining, drafting and writing? [20:59] <AtomicSpark> And how exactly dual booting works. [20:59] <philbull> with the writing, not very far [21:00] <philbull> all of the other stuff is on the wiki [21:00] <philbull> so, what are the most common problems that people deal with when installing? [21:01] <philbull> dual booting and partitioning, definitely [21:01] <philbull> but also post-install stuff like hardware [21:01] <philbull> problems with the bootloader too [21:02] <j1mc> problems with the bootloader are definitely scary for new users. [21:02] <philbull> so, I think there is a case for providing a brief, basic walkthrough [21:02] <philbull> lots of pictures etc [21:02] <j1mc> philbull: what approach could be taken to revive the team around this? [21:03] <philbull> then separate, focused how-tos (for partitioning/dual-booting) and troubleshooting material [21:03] <j1mc> that seems like the biggest issue... getting people involved again. [21:03] <AtomicSpark> Hardware and drivers. Internet stuff like Flash and Java (although we have topics that cover this). [21:03] <mdke> I think getting the doc into the branch with a structure might help people get involved [21:03] <philbull> people in the Manual Team might be interested [21:04] <philbull> I want to write this in plain text first, before we do any markup [21:04] <mdke> ah [21:04] <philbull> that should really lower the bar to contribution [21:04] <philbull> I can mark stuff up in about an afternoon [21:04] <philbull> there's no point other people worrying about it, the content is by far the most important part [21:05] <mdke> 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] <philbull> AtomicSpark: we have to be careful with what constitutes "installation" and what is "New to ubuntu" [21:05] <philbull> mdke: not initially [21:05] <AtomicSpark> True. I was just throwing things up there. ;) [21:05] <philbull> of course, someone (probably me) edits together a coherent draft [21:05] <mdke> right [21:05] <philbull> the peer review can be continuous, but informal [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 [21:06] <philbull> sure, that would be a very good idea [21:06] <philbull> we need to make a firm spec for the installation guide, though [21:06] <mdke> different to the existing one? [21:06] <philbull> maybe modify it [21:07] <philbull> we have to be clear on how it interacts with the New to Ubuntu docs [21:07] <mdke> I'd suggest modifying rather than starting again, it looks in decent shape [21:07] <mdke> true [21:07] <philbull> people are always tempted to start explaining how to add applications [21:07] <mdke> yes, that sort of thing is clearly not installing Ubuntu [21:07] <philbull> the IG should be short and sweet, installation only [21:08] <mdke> agreed [21:08] <philbull> so, maybe we should discuss this more on-list [21:08] <philbull> there should be some really fun potential for new contributors here [21:08] <philbull> some nice, difficult problems for people to explain in a user-friendly way [21:09] <mdke> will you take it forward on the list then? [21:10] <philbull> sure [21:10] <mdke> cool [21:10] <philbull> shall we move on? [21:10] <mdke> [ACTION] philbull to raise the installation-guide on the list and plan future action [21:10] <mdke> yep, next topic [21:10] <mdke> Setting out a Requirements document to guide our efforts [21:10] <philbull> this is an interesting idea [21:11] <philbull> sort of like a manifesto? [21:11] <mdke> I think what Kyle was saying was basically this [21:11] <mdke> Discussions on the list sometimes get unfocused because of a lack of understanding about what the team does [21:12] <mdke> and what it's objectives are [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 [21:12] <j1mc> mdke: i think it also takes into consideration our own roles as "upstream" doc providers. [21:13] <mdke> calling it a "requirements document" seems a bit rigid to me, I don't think we really have such things [21:13] <j1mc> which i'm not so sure we had really considered so much before [21:13] <philbull> I think having a brief list of what we're trying to achieve with the docs would be nice [21:13] <mdke> j1mc: could be, I know he has that in mind often [21:13] <j1mc> i think that setting up "requirements" of some sort would be helpful in deciding what syntax to use... [21:13] <philbull> ah, yes [21:14] <philbull> j1mc: who are we upstream of? [21:14] <j1mc> that way we can lay out what is important to us and see which platform best meets our needs. [21:14] <j1mc> philbull: OEM's who redistribute ubuntu. [21:14] <mdke> philbull: Ubuntu gets customised by quite a few distributors [21:14] <philbull> who in particular? [21:14] <mdke> dell? [21:14] <j1mc> dell [21:14] <j1mc> system76 [21:14] <nixternal> system76 [21:14] <nixternal> zareason [21:15] <j1mc> i'm not sure who all else [21:15] <nixternal> and quite a few more [21:15] <philbull> do we have contacts with these people? (for docs, in particular) [21:15] <mdke> various netbook providers maybe [21:15] <mdke> philbull: I think Kyle is in charge of that side of things in Canonical's OEM team [21:15] <j1mc> philbull: i'm sure that kyle does [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 [21:17] <j1mc> i'm not familiar with writing a requirements document, though [21:17] <j1mc> mdke: exactly [21:18] <j1mc> mdke: one thing that hasn't reall come up yet with regards to mallard are the server docs. [21:18] <mdke> that would be part and parcel of trying and testing Mallard out [21:18] <j1mc> we need to keep their requirements in mind, too [21:18] <j1mc> yeah - just mentioning it as i don't think it had been mentioned before [21:18] <mdke> j1mc: it isn't essential that the server guide migrates. [21:18] <j1mc> mdke: yes. [21:18] <mdke> personally it hadn't occurred to me that the server guide would move away from docbook [21:19] <mdke> it's a self contained guide so Mallard's aims don't necessarily apply [21:19] <j1mc> mdke: sorry... i misread what you had said. [21:20] <j1mc> server guide could probably stay on docbook, though i'm not as familiar with it. [21:20] <j1mc> it is the first thing i remove when i go to set up xubuntu docs. :) [21:20] <mdke> heh [21:20] <mdke> so, how about this by way of actions [21:21] <j1mc> so for an action item regarding the requirements doc - [21:21] <dhillon-v10> j1mc: one quick question: the server guide isn't going to be removed from ubuntu-docs right ? [21:21] <mdke> [ACTION] as part of testing Mallard, a spec to be drafted setting out what Mallard needs to do for us [21:21] <mdke> [ACTION] [21:21] <mdke> whoops [21:21] <j1mc> mdke: [/ACTION] :-P [21:21] <mdke> [ACTION] team to prepare a document setting out aims of writing desktop documentation including Topic based help [21:22] <mdke> [ACTION] general resolve to update style guide to continue :) [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. [21:22] <j1mc> s/for/from [21:22] <mdke> j1mc: sounds good [21:23] <j1mc> moving on? [21:23] <mdke> moving on :) [21:23] <mdke> D"What should we do about screenshots?" [21:23] <j1mc> dhillon-v10: sorry... no, the serverguide WILL remain in ubuntu docs [21:23] <j1mc> we aren't going to remove it [21:23] <j1mc> mdke: i like your suggestion of mostly using screenshots that don't feature text [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 [21:25] <mdke> as there would be bound to be screenshots that don't get translated [21:25] <mdke> taking good screenshots isn't so easy, extrapolate that over 50 languages and we are in trouble [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. [21:25] <mdke> so yeah, I'm +1 on a policy for textless icons [21:25] <j1mc> here's an interesting page, though: http://www.google.com/support/chrome/bin/answer.py?hl=es&answer=95606 [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 [21:26] <mdke> dunno if that is possible though [21:26] <mdke> j1mc: heh [21:26] <j1mc> mdke: i wouldn't think so [21:26] <mdke> anything is possible! [21:27] <j1mc> hehe - ok, we'll aim for that for lucid+4 :) [21:27] <mdke> I'll maybe just file a bug on yelp [21:27] <mdke> :p [21:27] <mdke> what do others think about this issue? [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. [21:29] <mdke> would we just liaise with the translators through the mailing list and undertake to upload translated images? [21:29] <j1mc> nixternal: ping ^^^ [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. [21:30] <j1mc> at least, i think we would. [21:31] <nixternal> I always wondered about translated images/screenshots myself [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 [21:32] <j1mc> mdke: in certain cases, i don't think having an untranslated screenshot is so bad. [21:32] <j1mc> if it isn't anything too specific - as long as it guides the user well enough. [21:32] <j1mc> they can match things up with their eyes. [21:33] <j1mc> but generally, i do strongly prefer images w/o text where possible. [21:33] <mdke> it's not so professional though, as your google chrome page shows [21:33] <j1mc> mdke: yeah. [21:34] <mdke> I would still prefer a textless images policy myself. philbull - any thoughts? [21:34] <philbull> images make the docs much more user friendly [21:35] <philbull> my connection dropped... did we discuss the issue of people confusing images for the real GUI? [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 [21:36] <philbull> I agree with j1mc, something is better than nothing in most cases [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 [21:37] <philbull> we should just try harder with the translation [21:37] <philbull> it's a pretty easy way of contributing [21:37] <philbull> (getting people to send in translated screenshots) [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 [21:37] <j1mc> i wonder if there is any way to automate screenshots. [21:38] <mdke> plus we'll have to take quite a bit of time uploading them all [21:38] <mdke> and the branch will get huge too [21:38] <j1mc> like, en_bg *take screenshot*... switch to de *screenshot*... switch to fr *screenshot*... [21:38] <philbull> I think we can get around all this, if we're smart about it [21:38] <j1mc> mdke: yeah, branch size would be an issue [21:38] <philbull> j1mc: I thought about that, but it would be a massive burden on us [21:39] <philbull> uploading doesn't need to take a long time [21:39] <philbull> maybe we can do a trial run, with just a few images? [21:40] <j1mc> i say that we use textless images unless we get team approval for something specific. [21:40] <j1mc> even in those cases, we should reach out to the translators [21:40] <philbull> how does this sit with the install CD space limitations? [21:40] <j1mc> make sure they are aware of the issues. [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 [21:41] <humphreybc> The manual will have localized screenshots you guys could use. [21:41] <philbull> humphreybc: how are you handling the translation of the screenshots? [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. [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! [21:44] <humphreybc> It would be groovy if we could have a screenshot library that we can both use [21:44] <humphreybc> to save space [21:45] <mdke> yeah [21:45] <mdke> we'll need some guidelines for taking useful screenshots too [21:45] <mdke> to avoid the confusion with the UI issue that philbull mentioned [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. [21:46] <j1mc> of course it is propriatary: http://www.google.com/support/chrome/bin/answer.py?hl=es&answer=95606 [21:46] <j1mc> ah, crap [21:46] <j1mc> sorry, wrong link [21:46] <humphreybc> sorry about that, laptop just ran out of juice as i plugged it in! [21:46] <mdke> there is an old page here that could be useful - https://wiki.ubuntu.com/TakingScreenshots [21:47] <humphreybc> what did I miss? [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. [21:47] <j1mc> http://www.bluemangolearning.com/blog/2010/01/experimental-screensteps-for-linux-beta/ [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. [21:48] <j1mc> a bit off topic, i know... [21:49] <mdke> ok, let's try and pull the strings together here [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 [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 [21:50] <humphreybc> What do you think about a shared screenshots package? [21:50] <mdke> package as in deb package? [21:50] <humphreybc> yes, in the repos [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 [21:51] <mdke> what would that be used for? [21:51] <humphreybc> Oh wait are you thinking of including screenshots in yelp or the online docs? [21:51] <humphreybc> Sorry I missed a fair chunk of the conversation earlier [21:51] <mdke> humphreybc: we're talking about the system docs right now, which are the same as you see on help.ubuntu.com [21:51] <mdke> the wiki already uses quite a few screenshots [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 [21:52] <humphreybc> so a shared screenshot package/database/library call it what you will, would make sense? [21:52] <mdke> how would the manual use such screenshots? Isn't it intended to be in a pdf? [21:53] <mdke> but anyway I can't conceive of a world where Ubuntu includes two separate help resources on the CD [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. [21:53] <mdke> images in pdfs need to be part of the pdf itself, afaik [21:54] <humphreybc> well many people couldn't conceive a world where machines build cars, but it happened :) [21:54] <mdke> that's a different type of conceiving [21:54] <humphreybc> Either way, I am certain that the screenshots from the manual project could be useful [21:54] <mdke> obviously, it's technically possible [21:54] <humphreybc> Especially seeing as they're localized [21:54] <humphreybc> (or, rather will be) [21:54] <mdke> yes, reusing good material is clearly a good idea [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 [21:55] <mdke> yeah, that's my feeling too [21:55] <humphreybc> Yeah I've always known that. It might not happen in time for Lucid [21:56] <humphreybc> It's just one of those wait and see things [21:56] <mdke> ok, let's move on [21:57] <mdke> don't think we resolved this issue but let's defer to the list in the interest of finishing the meeting [21:57] <mdke> last item is: [21:57] <mdke> Screencasts team up for adoption [21:57] <mdke> popey: around? [21:57] <humphreybc> I think he said he couldn't make it, mdke [21:57] <mdke> yeah, but his session may have finished by now [21:58] <mdke> let's see [21:58] <mdke> ah, looks like someone else took over his session so maybe he isn't around at all [21:58] <mdke> ok, deferred to the next meeting :) [21:59] <mdke> thanks everyone and we'll follow up on the list with the various action items [21:59] <humphreybc> cool, enjoy the rest of your weekend matt [21:59] <j1mc> mdke: it's been two hours - i can follow-up about xubuntu docs at a later time. [21:59] <mdke> oh sorry, I didn't see that extra item [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. [22:00] <mdke> j1mc: up to you [22:00] <mdke> j1mc: what's the current status? [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 [22:01] <j1mc> mdke: i've switched all of the docs to use a xubuntu-menus-C entity file [22:01] <j1mc> instead of gnome-menus-C [22:01] <j1mc> and modified the docs to validate against that 22:01:39 < j1mc> but other than that, they still are ubuntu-specific 22:02:01 < j1mc> still, i'd like to get an html build ready within about 2 weeks. 22:02:20 < mdke> ok, I'm happy to help with that 22:02:32 < j1mc> i am more experienced with things now, but will surely have some questions for you. 22:02:40 < mdke> no problem 22:02:45 < j1mc> thanks, mdke 22:03:06 < mdke> no worries - let's call the meeting closed :) |
=== head_v is now known as head_victim [16:54] <Rocket2DMn> Meeting in 5 minutes? [16:57] <j1mc> meeting in a few minutes [16:58] <Rocket2DMn> hey j1mc , how are you? [16:59] <j1mc> hi there, Rocket2DMn :) [16:59] <j1mc> Rocket2DMn: you are Connor, right? [16:59] <Rocket2DMn> yup [17:00] <mdke> evening chaps [17:00] <j1mc> hello, mdke [17:00] <Rocket2DMn> hey mdke , long time no see, hope you are well [17:00] <mdke> happy new year [17:01] <mdke> not bad thanks, how are you guys? [17:01] <j1mc> same to you! [17:01] <j1mc> pretty good here. :) [17:01] <Rocket2DMn> doing well here [17:01] <mdke> hey philbull [17:01] <j1mc> philbull: o/ [17:01] <philbull> hey [17:02] <j1mc> so far we have myself, philbull, mdke, Rocket2DMn ... anyone else? [17:04] <j1mc> shall we get started? [17:04] <mdke> sure [17:04] <philbull> yep [17:05] <j1mc> so, i think that the options around the docs have been pretty well hashed-out on the mailing list [17:06] <j1mc> does anyone have anything to add re: copyright assignment agreement [17:07] <Pendulum> I have a question, how is this going to effect future people who want to be involved with docs and want to write unity documentation? [17:07] <mdke> I think that at the moment, enough core contributors object to copyright assignment that we should format plans on the basis that it should not be required [17:07] <Pendulum> I realise that as a whole the team doesn't want to be involved with it, but does that mean that they'd have to have a separate project? [17:08] <mdke> Pendulum: I guess that depends on how we decide to proceed. We're not talking about not being involved with unity documentation. If Ubuntu uses Unity, and we're writing documentation for Ubuntu, we'll need to write for Unity [17:08] <j1mc> Pendulum: i don't think that there would need to be a "unity docs team," but there would be a unity-docs repository [17:08] <Pendulum> okay, that makes sense. I just wasn't clear :) [17:08] <mdke> j1mc: would there? [17:08] <philbull> I had some emails about this from Canonical people [17:09] <Pendulum> (and as it's about to come up that my team -the accessibility team- is going to be looking for some documentation guidance soon specifically Unity-related) [17:09] <philbull> They said they'd talk to me in the New Year [17:09] <philbull> (don't know when; guess they're pretty busy about now) [17:09] <Rocket2DMn> Would upstream unity documentation exist in the gnome-user-docs? [17:09] <mdke> Rocket2DMn: I don't see how it can; unity hasn't been accepted into gnome as far as I understand [17:09] <philbull> Rocket2DMn: No, it won't [17:10] <j1mc> mdke: if someone wanted to explicity document unity only, i would think that there would need to be a repository for that [17:10] <shaunm> Pendulum: how much of the accessibility user experience will be the same as with stock gnome in a unity-using ubuntu? [17:10] <philbull> The gnome-user-docs will be firmly based on gnome-shell [17:10] <mdke> j1mc: that would be an upstream issue I guess [17:10] <Rocket2DMn> ok, thanks, i wasn't sure if Gnome was using Unity [17:10] <Pendulum> shaunm: they're having to write an accessibility framework for Unity so we're not even sure yet because there functionality hasn't made it in yet [17:11] <Pendulum> (it's due Alpha2) [17:11] <shaunm> ok [17:11] <shaunm> Pendulum: but given all the atk bridges and such, orca would still be used for screen reading and braille, yes? [17:11] <mdke> philbull: I don't think you have commented on the mailing list about the various options, I was interested to find out how you see things [17:12] <Pendulum> shaunm: orca yes, but I'm not sure any decision has been made about some of the other things -- but I suspect this is a larger conversation that should come outside of this meeting :) [17:12] <j1mc> mdke: upstream being "unity developers" in this case? [17:12] <philbull> mdke: First of all, I'm tremendously pissed off about the whole thing [17:12] <mdke> j1mc: I guess so [17:12] <philbull> The copyright assignment thing is really divisive [17:13] <philbull> Whatever we do, we risk wasting our time [17:13] <mdke> well [17:13] <zkriesse> Oh doc meeting? [17:13] <mdke> that's the case of any contributions to Ubuntu, it's not a documentation specific issue [17:13] <philbull> true [17:13] <mdke> I feel the same way, but I think it's not a documentation issue specifically [17:14] <philbull> Yes, but we need to talk about the docs here [17:14] <mdke> sure [17:14] <philbull> Ideally, they'd stop requiring the CCA [17:14] <czajkowski> aye the same could be said about a patch [17:15] <philbull> My worry is that the same thing will happen with the Unity docs as happened with the gnome-app-install/software-center docs [17:15] <philbull> We had docs for that, and someone at Canonical just wrote their own and put them directly in the package [17:15] <j1mc> philbull: i wasn't aware of that [17:16] <j1mc> philbull: did someone request the ubuntu-doc author(s) to sign the copyright agreement? [17:16] <philbull> j1mc: Yes, the docs for software-center weren't written by the Ubuntu Docs team! [17:16] <mdke> mpt wrote them, iirc [17:16] <philbull> j1mc: Not in that case. As far as I'm aware, we didn't even hear about them [17:17] <Rocket2DMn> Quick question guys - are there currently any docs for Unity in any format? [17:17] <mdke> not as far as I know [17:17] <j1mc> Rocket2DMn: not that i'm aware of... are there any docs from the netbook edition that used the Unity layout? [17:18] <Rocket2DMn> Not sure, I'm afraid I've been out of the loop a fair amount since we released Lucid [17:19] <Rocket2DMn> Never did any netbook documentation either [17:19] <mdke> philbull: that particular issue may have been a problem of lack of communication between docteam and development team; here I think we have a more subtle issue [17:19] <philbull> mdke: Perhaps, but I wanted to point out that there is precedent [17:19] <mdke> which is that reasons of principle might prevent us from contributing upstream or to the package [17:20] <mdke> realistically is there any other option than modifying ubuntu-docs to fit unity and carrying on as before? [17:20] <Rocket2DMn> mdke, tbh, if you can ever get a development team to communicate effectively and in a timely manner with a doc team,, you're achieving something that few groups have been able to pull off and maintain [17:20] <j1mc> let's say that canonical develops their own unity-docs package, would it be possible to integrate our docs with it? [17:21] <Rocket2DMn> Sorry if that sounds skeptical [17:21] <j1mc> Rocket2DMn: i think that is a problem of many developer/documentor relationships - not just in ubuntu / canonical. [17:22] <mdke> j1mc: I guess it depends on how it is done. If they follow a similar strategy to gnome-user-docs, and write in Mallard, then I suppose there is no reason why not [17:22] <Rocket2DMn> j1mc, yes, and as a professional software dev, I know both sides of it [17:22] <philbull> j1mc: Yes, it wouldn't be as pretty, but it would work [17:22] <philbull> Especially if they use Mallard. We can just symlink it in (although there may be subtle licensing issues there) [17:23] <dhillon-v10> philbull: ping [17:24] <j1mc> philbull: good point re: licensing issues [17:24] <philbull> mdke: Realistically, I don't think there is any other option but to modify ubuntu-docs [17:24] <mdke> philbull: me neither [17:25] <philbull> The modifications wouldn't be too difficult for the most part [17:25] <philbull> We'd just replace all of the launching instructions with Unity-specific ones [17:25] <mdke> I haven't tried Unity yet. Is it easy to run in a VM? [17:25] <mdke> I think I've read that it isn't [17:25] <philbull> Although there is the issue of the fallback GNOME 2 UI... [17:26] <j1mc> mdke: like gnome-shell, i don't think it can be run in a VM [17:26] <Pendulum> j1mc: that's the experience I've had [17:26] <shaunm> philbull: we don't even have a good docs story for fallback in gnome [17:26] <Rocket2DMn> I think Unity required 3d acceleration which could make it difficult to run in a VM depending on your setup [17:26] <Pendulum> there might be a version of virtualbox that will do it [17:26] <Pendulum> but most VMs can't do the 3D acceleration [17:27] <mdke> philbull: as to fallback, I think the first thing is to document the default; we have only rarely documented non-default software [17:27] <Rocket2DMn> Pendulum, i think you're right that vbox can, i'm not sure how good it is though. Regardless of performance, as long as we can get it to run we can document it [17:27] <Pendulum> yeah [17:28] <philbull> mdke: The thing is, lots of people will be experiencing the fallback! [17:28] <mdke> philbull: really? [17:28] <philbull> I think so, yes [17:28] <mdke> oh dear [17:28] <philbull> It depends on whether graphics acceleration is well-supported, I think [17:28] <Pendulum> it is also in some ways less of a fallback this time and more of a choice. Both will actually be an option when you log in from the default install [17:28] <philbull> I've plenty of experience with chipsets that don't like Compiz [17:29] <mdke> shaunm: can you think of any easy way to provide alternative documentation depending on the desktop used? I can't [17:29] <philbull> conditionals again... [17:29] <j1mc> could we just provide a somewhat updated version (or a version with some "note" admonitions) of our current docs for that? [17:29] <j1mc> ... for the fallback? [17:29] <mdke> j1mc: the difficulty is how to figure out when it should be shown and when the unity version should be shown [17:30] <shaunm> mdke: easy way? no, I can't. ideally, the fallback experience would be something that mimics the full experience closely enough that most textual instructions are still correct. but that's not what's happening [17:30] <j1mc> perhaps provide a topic... if you are using the two-panel gnome layout... use these docs... [17:30] <mdke> shaunm: nod [17:31] <mdke> will gnome-shell have similar fallback issues as unity? [17:31] <shaunm> yes [17:31] <mdke> doh [17:31] <mdke> so yelp can't pick up which desktop is being used? [17:31] <philbull> There is an easy (but hacky) way [17:32] <shaunm> I'm sure we could figure out a way for yelp to know what desktop shell you're using. an x window property or envar or something. [17:32] <philbull> We have a script that detects the desktop and launches Yelp with the right documents open [17:33] <shaunm> if the writers actually have the time to create and maintain dual docs like that, I'll figure out the technical end in yelp [17:33] <mdke> will the next version of Ubuntu have yelp 3 or yelp 2? [17:34] <shaunm> I would think 3, but I don't know for certain [17:34] <mdke> hope so [17:34] <philbull> If we're shipping GNOME3 apps, we'll be able to ship Yelp 3 [17:35] <mdke> anyway, as you say, it's quite a heavy burden to maintain two sets of docs [17:35] <mdke> apart from the need to figure out how they should live alongside each other and where they should share the same material [17:35] <Pendulum> Maybe it's a good time to do some serious recruitment? I know I'm far from the only person who has been interested in documentation for ages but felt like other than wiki work, it was difficult to get involved [17:36] <mdke> yes, this is something we've struggled with for a long time [17:37] <Rocket2DMn> There are a lot of things people need to learn to contribute - bzr (and version control in general), docbook, update and release processes, etc [17:38] <Pendulum> Right, but I have to say that in the past year it's seemed to me that rather than try to teach new people, the default thing has been "here this is what you can do on the wiki". I wonder if there's a way to do doc papercuts so that there are some small things that are easier to use as tools to teach newcomers [17:39] <shaunm> question: will the gnome 2 fallback be more or less the same in ubuntu as in gnome-shell? [17:39] <Rocket2DMn> Pendulum, before we get into that discussion, is there more we want to talk about for Unity? [17:39] <mdke> I'm sure we can do a lot better in that direction [17:39] <mdke> anyway, before we can figure out how to make contributing easier, we need to figure out what we are going to work on ourselves [17:39] <mdke> shaunm: I would assume so but don't know for sure [17:39] <Pendulum> shaunm: as far as I've heard, yes [17:40] <shaunm> (aside from the differences that already exist, which aren't trivial from a docs perspective) [17:40] <mdke> indeed [17:42] <mdke> are the differences so great as to make it impossible to ship single documentation which can be used for both environments? [17:43] <j1mc> mdke: by "both environments," you mean unity and the gnome2 layout? [17:43] <mdke> if the differences are just about how to open things or where to find things, we might be able to explain how to do those actions on both desktops, and keep the rest of our language neutral and just refer back to those topics when necessary [17:43] <mdke> j1mc: yeah [17:44] <shaunm> in my (limited) experience with unity, it didn't even offer an easy way to get to nautilus. it just has that Files screen. that's a huge chunk of the docs [17:44] <j1mc> i think that having, "if you are using this desktop, do this..." and "if you are using that desktop, do that..." gets pretty cumbersome as a reader, though. [17:45] <mdke> j1mc: yes, that's certainly not what I had in mind [17:45] <j1mc> i experience that at my work, where different teams are using different releases of the same platform, so they have to follow different instructions [17:46] <j1mc> ... we have 15 min left on our hour's time [17:46] <mdke> but if we can do instructions like "Open X", with "Open" being a link on how to open applications on each environment, then we at least keep the differences in self-contained places [17:47] <mdke> perhaps we should experiment a bit with Unity in order to get some ideas about this issue [17:47] <shaunm> I could add conditional processing in the yelp 3 time frame, but: (1) do people have the time and inclination to maintain conditional docs, (2) the current conditional processing proposal has no way to push or replace contents, which means unity instructions either have to be put into gnome docs, or you'd have to patch [17:48] <j1mc> yes, i tried alpha1 on my laptop for a bit. i couldn't get unity to work, though. [17:48] <philbull> I think the plan with Unity might be to go with Zeitgeist/Activity Journal instead of nautilus [17:48] <philbull> not sure, though [17:50] <philbull> How about this: [17:50] <philbull> We do a simple overview of Unity, discussing basic usage [17:51] <philbull> We replace the "Gnome Shell Overview" in the new GNOME desktop help with that by manually patching it out (no need for Mallard conditionals) [17:52] <philbull> The desktop help will give us topics on connecting to the internet, managing files and folders, and so on [17:52] <Rocket2DMn> Another issue that could pop up if we are to select different documentation to display depending on the environment, is how do we deploy our html docs? [17:52] <philbull> That will give us functional, if incomplete, help [17:53] <mdke> philbull: when you say desktop help, are you talking about ubuntu-docs or gnome-user-docs? [17:53] <philbull> gnome-user-docs [17:53] <j1mc> philbull: the new ones that are being worked-on now? [17:53] <mdke> so would you jettison ubuntu-docs entirely? [17:53] <philbull> j1mc: yes [17:54] <philbull> mdke: Not all of it, but lots of it is already obsolete [17:54] <mdke> do you think that gnome help is going to be suitable for adoption in that way? [17:55] <philbull> mdke: Yes, i think so [17:55] <mdke> my concern is that Ubuntu seems to moving away from Gnome, rather than closer, so if we are moving in the opposite direction, that might not work in the long term [17:55] <j1mc> mdke: correct, but using what gnome has right now as a jumping-off point would work [17:55] <philbull> mdke: true, but the GNOME desktop-help is currently split into a number of topic areas [17:56] <j1mc> ubuntu-docs wouldn't need to stay synced with gnome-shell/gnome-user-docs on an ongoing basis [17:56] <philbull> we can take whatever is relevant, and its Mallardyness will allow us to do that without too much patching [17:56] <mdke> is it reasonably complete? [17:56] <j1mc> but having those mallard topics as a starting point would be helpful [17:56] <philbull> mdke: Not yet, we need help! [17:56] <mdke> ok. This is definitely an interesting idea [17:57] <mdke> although we need to give more thought to it than is available at this meeting, I suspect. In particular we should focus on whether patching in/out material will raise the barrier to entry [17:57] <Rocket2DMn> I like this, if I'm understanding correctly, we'll be able to use more upstream documentation on basic usage which can replace material we already have [17:57] <j1mc> philbull: could you provide the git repo information of the current gnome docs? [17:59] <mdke> let's have a look at the docs, at Unity, think about how much patching will be required, and perhaps have another meeting? [18:00] <j1mc> mdke: i think that sounds good [18:00] <philbull> j1mc: Sure: http://git.gnome.org/browse/gnome-user-docs/ [18:01] <philbull> mdke: Sounds good, can you raise this on the mailing list please? [18:02] <mdke> ok. I will try to summarise the idea and some of the issues on the mailing list and then we can come back, perhaps even a similar time next week? [18:02] <Rocket2DMn> That works for me [18:03] <philbull> yep [18:03] <j1mc> works for me, too [18:03] <mdke> cool [18:03] <j1mc> thanks, all! [18:04] <mdke> catch you soon [18:05] <philbull> thanks! [18:06] <Rocket2DMn> mdke, any idea what we need to do for bug 555813 ? [18:06] <ubot2> Launchpad bug 555813 in ubuntu-docs (Ubuntu) (and 1 other project) "Please, delete the unnecesary es_PR and es_ES templates for ubuntu-docs-about-ubuntu (affects: 1) (heat: 14)" [Undecided,New] https://launchpad.net/bugs/555813 |
This is a meeting summary and log for the DocumentationTeam meeting of 23 January 2010.
Agenda
- ...
Summary
- ...
Log
1 === head_v is now known as head_victim
2 [16:54] <Rocket2DMn> Meeting in 5 minutes?
3 [16:57] <j1mc> meeting in a few minutes
4 [16:58] <Rocket2DMn> hey j1mc , how are you?
5 [16:59] <j1mc> hi there, Rocket2DMn :)
6 [16:59] <j1mc> Rocket2DMn: you are Connor, right?
7 [16:59] <Rocket2DMn> yup
8 [17:00] <mdke> evening chaps
9 [17:00] <j1mc> hello, mdke
10 [17:00] <Rocket2DMn> hey mdke , long time no see, hope you are well
11 [17:00] <mdke> happy new year
12 [17:01] <mdke> not bad thanks, how are you guys?
13 [17:01] <j1mc> same to you!
14 [17:01] <j1mc> pretty good here. :)
15 [17:01] <Rocket2DMn> doing well here
16 [17:01] <mdke> hey philbull
17 [17:01] <j1mc> philbull: o/
18 [17:01] <philbull> hey
19 [17:02] <j1mc> so far we have myself, philbull, mdke, Rocket2DMn ... anyone else?
20 [17:04] <j1mc> shall we get started?
21 [17:04] <mdke> sure
22 [17:04] <philbull> yep
23 [17:05] <j1mc> so, i think that the options around the docs have been pretty well hashed-out on the mailing list
24 [17:06] <j1mc> does anyone have anything to add re: copyright assignment agreement
25 [17:07] <Pendulum> I have a question, how is this going to effect future people who want to be involved with docs and want to write unity documentation?
26 [17:07] <mdke> I think that at the moment, enough core contributors object to copyright assignment that we should format plans on the basis that it should not be required
27 [17:07] <Pendulum> I realise that as a whole the team doesn't want to be involved with it, but does that mean that they'd have to have a separate project?
28 [17:08] <mdke> Pendulum: I guess that depends on how we decide to proceed. We're not talking about not being involved with unity documentation. If Ubuntu uses Unity, and we're writing documentation for Ubuntu, we'll need to write for Unity
29 [17:08] <j1mc> Pendulum: i don't think that there would need to be a "unity docs team," but there would be a unity-docs repository
30 [17:08] <Pendulum> okay, that makes sense. I just wasn't clear :)
31 [17:08] <mdke> j1mc: would there?
32 [17:08] <philbull> I had some emails about this from Canonical people
33 [17:09] <Pendulum> (and as it's about to come up that my team -the accessibility team- is going to be looking for some documentation guidance soon specifically Unity-related)
34 [17:09] <philbull> They said they'd talk to me in the New Year
35 [17:09] <philbull> (don't know when; guess they're pretty busy about now)
36 [17:09] <Rocket2DMn> Would upstream unity documentation exist in the gnome-user-docs?
37 [17:09] <mdke> Rocket2DMn: I don't see how it can; unity hasn't been accepted into gnome as far as I understand
38 [17:09] <philbull> Rocket2DMn: No, it won't
39 [17:10] <j1mc> mdke: if someone wanted to explicity document unity only, i would think that there would need to be a repository for that
40 [17:10] <shaunm> Pendulum: how much of the accessibility user experience will be the same as with stock gnome in a unity-using ubuntu?
41 [17:10] <philbull> The gnome-user-docs will be firmly based on gnome-shell
42 [17:10] <mdke> j1mc: that would be an upstream issue I guess
43 [17:10] <Rocket2DMn> ok, thanks, i wasn't sure if Gnome was using Unity
44 [17:10] <Pendulum> shaunm: they're having to write an accessibility framework for Unity so we're not even sure yet because there functionality hasn't made it in yet
45 [17:11] <Pendulum> (it's due Alpha2)
46 [17:11] <shaunm> ok
47 [17:11] <shaunm> Pendulum: but given all the atk bridges and such, orca would still be used for screen reading and braille, yes?
48 [17:11] <mdke> philbull: I don't think you have commented on the mailing list about the various options, I was interested to find out how you see things
49 [17:12] <Pendulum> shaunm: orca yes, but I'm not sure any decision has been made about some of the other things -- but I suspect this is a larger conversation that should come outside of this meeting :)
50 [17:12] <j1mc> mdke: upstream being "unity developers" in this case?
51 [17:12] <philbull> mdke: First of all, I'm tremendously pissed off about the whole thing
52 [17:12] <mdke> j1mc: I guess so
53 [17:12] <philbull> The copyright assignment thing is really divisive
54 [17:13] <philbull> Whatever we do, we risk wasting our time
55 [17:13] <mdke> well
56 [17:13] <zkriesse> Oh doc meeting?
57 [17:13] <mdke> that's the case of any contributions to Ubuntu, it's not a documentation specific issue
58 [17:13] <philbull> true
59 [17:13] <mdke> I feel the same way, but I think it's not a documentation issue specifically
60 [17:14] <philbull> Yes, but we need to talk about the docs here
61 [17:14] <mdke> sure
62 [17:14] <philbull> Ideally, they'd stop requiring the CCA
63 [17:14] <czajkowski> aye the same could be said about a patch
64 [17:15] <philbull> My worry is that the same thing will happen with the Unity docs as happened with the gnome-app-install/software-center docs
65 [17:15] <philbull> We had docs for that, and someone at Canonical just wrote their own and put them directly in the package
66 [17:15] <j1mc> philbull: i wasn't aware of that
67 [17:16] <j1mc> philbull: did someone request the ubuntu-doc author(s) to sign the copyright agreement?
68 [17:16] <philbull> j1mc: Yes, the docs for software-center weren't written by the Ubuntu Docs team!
69 [17:16] <mdke> mpt wrote them, iirc
70 [17:16] <philbull> j1mc: Not in that case. As far as I'm aware, we didn't even hear about them
71 [17:17] <Rocket2DMn> Quick question guys - are there currently any docs for Unity in any format?
72 [17:17] <mdke> not as far as I know
73 [17:17] <j1mc> Rocket2DMn: not that i'm aware of... are there any docs from the netbook edition that used the Unity layout?
74 [17:18] <Rocket2DMn> Not sure, I'm afraid I've been out of the loop a fair amount since we released Lucid
75 [17:19] <Rocket2DMn> Never did any netbook documentation either
76 [17:19] <mdke> philbull: that particular issue may have been a problem of lack of communication between docteam and development team; here I think we have a more subtle issue
77 [17:19] <philbull> mdke: Perhaps, but I wanted to point out that there is precedent
78 [17:19] <mdke> which is that reasons of principle might prevent us from contributing upstream or to the package
79 [17:20] <mdke> realistically is there any other option than modifying ubuntu-docs to fit unity and carrying on as before?
80 [17:20] <Rocket2DMn> mdke, tbh, if you can ever get a development team to communicate effectively and in a timely manner with a doc team,, you're achieving something that few groups have been able to pull off and maintain
81 [17:20] <j1mc> let's say that canonical develops their own unity-docs package, would it be possible to integrate our docs with it?
82 [17:21] <Rocket2DMn> Sorry if that sounds skeptical
83 [17:21] <j1mc> Rocket2DMn: i think that is a problem of many developer/documentor relationships - not just in ubuntu / canonical.
84 [17:22] <mdke> j1mc: I guess it depends on how it is done. If they follow a similar strategy to gnome-user-docs, and write in Mallard, then I suppose there is no reason why not
85 [17:22] <Rocket2DMn> j1mc, yes, and as a professional software dev, I know both sides of it
86 [17:22] <philbull> j1mc: Yes, it wouldn't be as pretty, but it would work
87 [17:22] <philbull> Especially if they use Mallard. We can just symlink it in (although there may be subtle licensing issues there)
88 [17:23] <dhillon-v10> philbull: ping
89 [17:24] <j1mc> philbull: good point re: licensing issues
90 [17:24] <philbull> mdke: Realistically, I don't think there is any other option but to modify ubuntu-docs
91 [17:24] <mdke> philbull: me neither
92 [17:25] <philbull> The modifications wouldn't be too difficult for the most part
93 [17:25] <philbull> We'd just replace all of the launching instructions with Unity-specific ones
94 [17:25] <mdke> I haven't tried Unity yet. Is it easy to run in a VM?
95 [17:25] <mdke> I think I've read that it isn't
96 [17:25] <philbull> Although there is the issue of the fallback GNOME 2 UI...
97 [17:26] <j1mc> mdke: like gnome-shell, i don't think it can be run in a VM
98 [17:26] <Pendulum> j1mc: that's the experience I've had
99 [17:26] <shaunm> philbull: we don't even have a good docs story for fallback in gnome
100 [17:26] <Rocket2DMn> I think Unity required 3d acceleration which could make it difficult to run in a VM depending on your setup
101 [17:26] <Pendulum> there might be a version of virtualbox that will do it
102 [17:26] <Pendulum> but most VMs can't do the 3D acceleration
103 [17:27] <mdke> philbull: as to fallback, I think the first thing is to document the default; we have only rarely documented non-default software
104 [17:27] <Rocket2DMn> Pendulum, i think you're right that vbox can, i'm not sure how good it is though. Regardless of performance, as long as we can get it to run we can document it
105 [17:27] <Pendulum> yeah
106 [17:28] <philbull> mdke: The thing is, lots of people will be experiencing the fallback!
107 [17:28] <mdke> philbull: really?
108 [17:28] <philbull> I think so, yes
109 [17:28] <mdke> oh dear
110 [17:28] <philbull> It depends on whether graphics acceleration is well-supported, I think
111 [17:28] <Pendulum> it is also in some ways less of a fallback this time and more of a choice. Both will actually be an option when you log in from the default install
112 [17:28] <philbull> I've plenty of experience with chipsets that don't like Compiz
113 [17:29] <mdke> shaunm: can you think of any easy way to provide alternative documentation depending on the desktop used? I can't
114 [17:29] <philbull> conditionals again...
115 [17:29] <j1mc> could we just provide a somewhat updated version (or a version with some "note" admonitions) of our current docs for that?
116 [17:29] <j1mc> ... for the fallback?
117 [17:29] <mdke> j1mc: the difficulty is how to figure out when it should be shown and when the unity version should be shown
118 [17:30] <shaunm> mdke: easy way? no, I can't. ideally, the fallback experience would be something that mimics the full experience closely enough that most textual instructions are still correct. but that's not what's happening
119 [17:30] <j1mc> perhaps provide a topic... if you are using the two-panel gnome layout... use these docs...
120 [17:30] <mdke> shaunm: nod
121 [17:31] <mdke> will gnome-shell have similar fallback issues as unity?
122 [17:31] <shaunm> yes
123 [17:31] <mdke> doh
124 [17:31] <mdke> so yelp can't pick up which desktop is being used?
125 [17:31] <philbull> There is an easy (but hacky) way
126 [17:32] <shaunm> I'm sure we could figure out a way for yelp to know what desktop shell you're using. an x window property or envar or something.
127 [17:32] <philbull> We have a script that detects the desktop and launches Yelp with the right documents open
128 [17:33] <shaunm> if the writers actually have the time to create and maintain dual docs like that, I'll figure out the technical end in yelp
129 [17:33] <mdke> will the next version of Ubuntu have yelp 3 or yelp 2?
130 [17:34] <shaunm> I would think 3, but I don't know for certain
131 [17:34] <mdke> hope so
132 [17:34] <philbull> If we're shipping GNOME3 apps, we'll be able to ship Yelp 3
133 [17:35] <mdke> anyway, as you say, it's quite a heavy burden to maintain two sets of docs
134 [17:35] <mdke> apart from the need to figure out how they should live alongside each other and where they should share the same material
135 [17:35] <Pendulum> Maybe it's a good time to do some serious recruitment? I know I'm far from the only person who has been interested in documentation for ages but felt like other than wiki work, it was difficult to get involved
136 [17:36] <mdke> yes, this is something we've struggled with for a long time
137 [17:37] <Rocket2DMn> There are a lot of things people need to learn to contribute - bzr (and version control in general), docbook, update and release processes, etc
138 [17:38] <Pendulum> Right, but I have to say that in the past year it's seemed to me that rather than try to teach new people, the default thing has been "here this is what you can do on the wiki". I wonder if there's a way to do doc papercuts so that there are some small things that are easier to use as tools to teach newcomers
139 [17:39] <shaunm> question: will the gnome 2 fallback be more or less the same in ubuntu as in gnome-shell?
140 [17:39] <Rocket2DMn> Pendulum, before we get into that discussion, is there more we want to talk about for Unity?
141 [17:39] <mdke> I'm sure we can do a lot better in that direction
142 [17:39] <mdke> anyway, before we can figure out how to make contributing easier, we need to figure out what we are going to work on ourselves
143 [17:39] <mdke> shaunm: I would assume so but don't know for sure
144 [17:39] <Pendulum> shaunm: as far as I've heard, yes
145 [17:40] <shaunm> (aside from the differences that already exist, which aren't trivial from a docs perspective)
146 [17:40] <mdke> indeed
147 [17:42] <mdke> are the differences so great as to make it impossible to ship single documentation which can be used for both environments?
148 [17:43] <j1mc> mdke: by "both environments," you mean unity and the gnome2 layout?
149 [17:43] <mdke> if the differences are just about how to open things or where to find things, we might be able to explain how to do those actions on both desktops, and keep the rest of our language neutral and just refer back to those topics when necessary
150 [17:43] <mdke> j1mc: yeah
151 [17:44] <shaunm> in my (limited) experience with unity, it didn't even offer an easy way to get to nautilus. it just has that Files screen. that's a huge chunk of the docs
152 [17:44] <j1mc> i think that having, "if you are using this desktop, do this..." and "if you are using that desktop, do that..." gets pretty cumbersome as a reader, though.
153 [17:45] <mdke> j1mc: yes, that's certainly not what I had in mind
154 [17:45] <j1mc> i experience that at my work, where different teams are using different releases of the same platform, so they have to follow different instructions
155 [17:46] <j1mc> ... we have 15 min left on our hour's time
156 [17:46] <mdke> but if we can do instructions like "Open X", with "Open" being a link on how to open applications on each environment, then we at least keep the differences in self-contained places
157 [17:47] <mdke> perhaps we should experiment a bit with Unity in order to get some ideas about this issue
158 [17:47] <shaunm> I could add conditional processing in the yelp 3 time frame, but: (1) do people have the time and inclination to maintain conditional docs, (2) the current conditional processing proposal has no way to push or replace contents, which means unity instructions either have to be put into gnome docs, or you'd have to patch
159 [17:48] <j1mc> yes, i tried alpha1 on my laptop for a bit. i couldn't get unity to work, though.
160 [17:48] <philbull> I think the plan with Unity might be to go with Zeitgeist/Activity Journal instead of nautilus
161 [17:48] <philbull> not sure, though
162 [17:50] <philbull> How about this:
163 [17:50] <philbull> We do a simple overview of Unity, discussing basic usage
164 [17:51] <philbull> We replace the "Gnome Shell Overview" in the new GNOME desktop help with that by manually patching it out (no need for Mallard conditionals)
165 [17:52] <philbull> The desktop help will give us topics on connecting to the internet, managing files and folders, and so on
166 [17:52] <Rocket2DMn> Another issue that could pop up if we are to select different documentation to display depending on the environment, is how do we deploy our html docs?
167 [17:52] <philbull> That will give us functional, if incomplete, help
168 [17:53] <mdke> philbull: when you say desktop help, are you talking about ubuntu-docs or gnome-user-docs?
169 [17:53] <philbull> gnome-user-docs
170 [17:53] <j1mc> philbull: the new ones that are being worked-on now?
171 [17:53] <mdke> so would you jettison ubuntu-docs entirely?
172 [17:53] <philbull> j1mc: yes
173 [17:54] <philbull> mdke: Not all of it, but lots of it is already obsolete
174 [17:54] <mdke> do you think that gnome help is going to be suitable for adoption in that way?
175 [17:55] <philbull> mdke: Yes, i think so
176 [17:55] <mdke> my concern is that Ubuntu seems to moving away from Gnome, rather than closer, so if we are moving in the opposite direction, that might not work in the long term
177 [17:55] <j1mc> mdke: correct, but using what gnome has right now as a jumping-off point would work
178 [17:55] <philbull> mdke: true, but the GNOME desktop-help is currently split into a number of topic areas
179 [17:56] <j1mc> ubuntu-docs wouldn't need to stay synced with gnome-shell/gnome-user-docs on an ongoing basis
180 [17:56] <philbull> we can take whatever is relevant, and its Mallardyness will allow us to do that without too much patching
181 [17:56] <mdke> is it reasonably complete?
182 [17:56] <j1mc> but having those mallard topics as a starting point would be helpful
183 [17:56] <philbull> mdke: Not yet, we need help!
184 [17:56] <mdke> ok. This is definitely an interesting idea
185 [17:57] <mdke> although we need to give more thought to it than is available at this meeting, I suspect. In particular we should focus on whether patching in/out material will raise the barrier to entry
186 [17:57] <Rocket2DMn> I like this, if I'm understanding correctly, we'll be able to use more upstream documentation on basic usage which can replace material we already have
187 [17:57] <j1mc> philbull: could you provide the git repo information of the current gnome docs?
188 [17:59] <mdke> let's have a look at the docs, at Unity, think about how much patching will be required, and perhaps have another meeting?
189 [18:00] <j1mc> mdke: i think that sounds good
190 [18:00] <philbull> j1mc: Sure: http://git.gnome.org/browse/gnome-user-docs/
191 [18:01] <philbull> mdke: Sounds good, can you raise this on the mailing list please?
192 [18:02] <mdke> ok. I will try to summarise the idea and some of the issues on the mailing list and then we can come back, perhaps even a similar time next week?
193 [18:02] <Rocket2DMn> That works for me
194 [18:03] <philbull> yep
195 [18:03] <j1mc> works for me, too
196 [18:03] <mdke> cool
197 [18:03] <j1mc> thanks, all!
198 [18:04] <mdke> catch you soon
199 [18:05] <philbull> thanks!
200 [18:06] <Rocket2DMn> mdke, any idea what we need to do for bug 555813 ?
201 [18:06] <ubot2> Launchpad bug 555813 in ubuntu-docs (Ubuntu) (and 1 other project) "Please, delete the unnecesary es_PR and es_ES templates for ubuntu-docs-about-ubuntu (affects: 1) (heat: 14)" [Undecided,New] https://launchpad.net/bugs/555813
MeetingLogs/DocTeam/January2011 (last edited 2011-03-07 15:38:05 by 208)