=== talsemgeest_ is now known as talsemgeest === bencrisford is now known as bencrisford_ === bencrisford_ is now known as bencrisford__ === bencrisford__ is now known as bencrisford_ [17:25] !ubot [17:25] Factoid 'ubot' not found [17:25] !status [17:25] Factoid 'status' not found [18:26] hey i have a question guys, I am working on reorgainzing the Backup section and to try and move a page should I just copy paste the content and then edit from there, or should i just link to it and have an admin rename/move the page? [18:45] hi all [18:49] hi philbull [18:49] hey j1mc [18:49] i've come prepared! [18:50] :) [18:56] can somone ping via via pm when we get started, I'll be by the machine but afk for a few min..... [18:57] technomensch: sure thing [19:00] ok... who all is here? :) [19:00] i am [19:00] hi BrunoXLambert [19:01] hi [19:01] * philbull is here [19:01] mwcrowley: you around? [19:01] yes [19:01] DougieRichardson: ? :-) [19:01] phil, glad u could make it [19:01] hey technomensch [19:01] present [19:01] dinda: ? you around? [19:01] dsas_: ? :) [19:02] dougie and matt haven't spoken up yet....not sure if they are @ keyboard yet [19:02] i sent an email to mdke earlier in the week. he's been swamped w/ work lately. [19:03] before we get started, did everyone get my link to review the "inprogress" version of the wiki playbook on google docs? [19:03] technomensch: i received it, but haven't haven't reviewed it yet, sorry. [19:04] Shall we go ahead and get started? I'm sure DougieRichardson can read-up when he gets to the keyboard. [19:04] Meeting Agenda is up at: https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda [19:04] j1, I'm trying to recall. whats your wiki id? [19:05] https://wiki.ubuntu.com/j1mc [19:05] ah....... [19:06] ok, i know it's a small group here today, but we can still cover some items. [19:06] we'll try to be brief. [19:06] he he, no chance [19:06] first - is anyone here new to the group? [19:06] I'm new [19:06] hi mwcrowley [19:07] hi all [19:07] care to briefly introduce yourself? [19:07] wait [19:07] j1 [19:07] want to start the meeting bot? [19:07] I am new there [19:07] I'm new as well [19:07] technomensch: let's not worry aboutit. [19:08] welcome, guys! [19:08] if you are new... welcome. :) [19:08] please just go ahead and introduce yourself in a sentence or two. :) [19:08] brief intro, I started using debian about five years ago, switched to Ubuntu on the desktop and I have some writing skills. So I'd like to find a place where I can give back. [19:08] coolness. [19:09] others? don't be shy. :) [19:09] I'm usung ubuntu since breezy. working at Revolution Linux with stgraber. I'm a support and trainnign guy [19:09] awesome. :) [19:09] My real name is Mark Strawser, I live in central PA and have been using Linux for about 10 years, non-continuously. So far I've just been getting my feet wet changing CategoryCleanups to Tags [19:10] great. :) [19:10] I'm Avi. I've switched into professional technical writing from public relations, and am excited to be a contributor to the new Karmic installation guide. I'm a relative linux newbie, but hope to bring the "average user" experience to the table. Wrote an installation guide to Intrepid and updated the Wubi wiki. [19:10] cool... welcome, avi1 [19:11] * DougieRichardson waves to j1mc - kids needed feeding [19:11] DougieRichardson: o/ [19:11] I'm Augustina! I've been active on the list but this is my first meeting. [19:11] welcome [19:11] great! lots of new people. [19:11] glad you could make it [19:11] anyone else? [19:11] * DougieRichardson o/ [19:12] missaugstina, don't worry, this is only the second meeting we've had within the last few months..... [19:12] someone had mentioned that they wanted to know different ways people could get involved w/ the project. [19:12] some info is here: https://wiki.ubuntu.com/DocumentationTeam/Organization [19:13] but chances are, if you're at this meeting, you're already familiar with some of what we do. [19:13] but you can get involved through the system documentation, work on the wiki, and even work on translations. [19:13] or any of the many guides such as the server guide [19:14] working on the documentation is a good way to build writing skills, learn some xml and wiki markup, and also learn about the ubuntu toolchain (launchpad, bzr, etc.) [19:14] did anyone have any particular questions for now? [19:15] j1, I propose a secondary meeting to educate on launchpad and bzr....etc...., maybe a mini-class [19:15] hi [19:15] mini-class would be good [19:16] what about the one from the openweek? [19:16] technomensch: cool - we had an ubuntu open week session that covered a lot of stuff from bzr and launchpad. [19:16] DougieRichardson: right [19:16] I'm in for a mini-class [19:16] any suggestions for a best first step. Are there any areas that need immediate help? [19:16] the problem with open week, are the international times [19:17] technomensch: doesn't stop us reusing the material though ;-) [19:17] here's a log of our session on bzr: https://wiki.ubuntu.com/MeetingLogs/openweekJaunty/DocsBzr [19:17] and here's the log of the session on docbook: https://wiki.ubuntu.com/MeetingLogs/openweekJaunty/DocsDocbook [19:17] those are good enough for me :) [19:18] emmajane did a good job with the docbook, and the bzr session was really good, too. [19:18] anything else for now? [19:18] * DougieRichardson shakes head [19:19] those links are a good place to start. [19:19] j1mc: sorry, are you going through an agenda? [19:19] https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda [19:20] shaunm: https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda [19:20] agenda ^^ [19:20] gracias [19:20] on to "Ye Olde Business" [19:20] someone put up, "How best to collaborate with translators" [19:20] but I think that might be a meeting topic on its own. [19:21] or, worthy of a meeting on its own... thoughts? [19:22] I wasn't aware there were any issues with translations at the moment? [19:23] if no-one has any specific issues we should move on [19:23] * DougieRichardson nods [19:23] Maybe it would be better to talk about this when Milo or some of the other translation folks are present. [19:23] yeah [19:24] DougieRichardson: anything on the Learning Initiative? [19:24] j1mc: not really no, they're still quite focussed on structure [19:25] they also keep holding meetings at really inconvenient times! [19:25] :) "structure" being the documentation structure, or . . . something else? [19:25] I think we need to look at the project and see how it suits us [19:25] do you have any links? [19:25] j1mc: team structure [19:25] I'm not familiar with this [19:25] philbull: yes wait one [19:26] https://wiki.ubuntu.com/Learning [19:26] sabdfl is very enthusiastic [19:27] initially it looked to integrate with the idea of classrooms/tutorials and so on quite well, its in Moodle [19:28] I've been wanting to learn moodle, so I wouldn't mind getting involved with that [19:28] so you are the doc team liason for the project? i suppose they'll let us know where they need help, or are they looking for us to be more active participants? [19:28] Matthew and I had a long chat with them, I offered to liase between the to initatives and there are some voices in canonical that are quite keen on the idea [19:28] j1mc:they want active participation [19:29] any word on integration with the docs? [19:29] I'm particularly interested in helping out with the Developer Documentation/tutorials since there seems to be a lack of it [19:29] training material goes alongside help resources [19:29] philbull: in what way? [19:29] well, via h.u.c or via links in Yelp? [19:29] I envisaged it as being a resource to train our members [19:30] there's no reason not to be able to integrate it in some way in that respect. [19:30] I was thinking more to do with the "How to use Ubuntu" bit [19:30] (i.e. for users) [19:30] I know, mdke was quite concerned with duplication of effort [19:30] * j1mc nods [19:31] there are lots of user assistance type projects floating around ubuntu at the moment [19:31] If I'm honest, I think the project might be a little ambitious and I have concerns about that section [19:31] we perhaps need to communicate with other initiatives more [19:31] missaugustina: have you seen the MOTU/GettingStarted wiki documentation? [19:31] missaugustina: https://wiki.ubuntu.com/MOTU/GettingStarted [19:32] motu are also involved in this initiative, although I haven't heard anything from them [19:32] DougieRichardson: i had hear a little about the learning team, but didn't get the scope of what they were doing, so i'm glad you brought this up. [19:33] query: would these be using the playbooks we're working on? [19:33] technomensch: possibly [19:33] missaugustina: you may also want to touch base with Nathan Handler (nhandler), as he has been doing some work on developer documentation. [19:34] The idea is a fair one - a centralised training resource. The execution, not so sure. This isn't just crossover with us but with Desktop Training course (which I and I know a few others here have worked on). [19:35] that would be quite an ambitious project [19:35] I have worries [19:36] I thiink that would be an understatement doug [19:36] it looks like i need to read through their meeting logs and mailing list to see what they're up to. [19:36] 1. there's a heavy forums influence on the project [19:36] 2. it duplicates, or has the potential to duplicate our efforts [19:36] 3. moodle / docbook integration needs work [19:37] DocBook? Why DocBook? [19:37] I think really, we need to read over all their logs and discuss it on list [19:37] can we decide on any action items concerning this for now? [19:37] Does anyone have any concerns? [19:37] Yep, I'd like to discuss this more on the list [19:38] philbull: because we use docbook and they use moodle [19:38] philbull: yeah, same here. [19:38] philbull: ^-^ [19:38] DougieRichardson: Ah, gotcha [19:39] OK, next item? [19:39] sure [19:39] that's you, phil: "introducing rigorous planning as a requirement..." [19:40] talk about a mouthful [19:40] Yes. I think that we should start planning things properly before we start writing them [19:40] second [19:40] Regarding the issue of Docbook and Moodle, would this be a reason to try to get multiple teams on DITA (which we will discuss later, I know) so that we can maximize reusable content. [19:40] I don't think that we do that enough at the moment [19:40] including reusable content b/w teams [19:40] we need to discuss DITA seperately. [19:41] ok, just keep this in mind for that discussion [19:41] I'm using the Installation Guide as a bit of a test run for more intensive planning/design [19:42] philbull: do you have any references that you can point us to for what you had in mind about doc planning? [19:42] Well, Lynda's stuff from WOSCON is useful [19:42] I should post it somewhere [19:42] that would be helpful [19:43] It doesn't have to be anything fancy [19:43] Just as long as we make sure that what we're writing is suitable and useful for our users... [19:43] ...before we write it. [19:44] are we talking about managing resources or defining prior to encoding? [19:44] For example, most of the topics in the system docs were added because they seemed like a good idea to the author [19:44] in otherwords, outlining and brainstorming, and maybe psydocoding.... [19:45] Pretty much. We should have a structure and a design brief in place before we produce any content [19:45] Look at the system docs [19:45] maybe we need to envisage a more object approach to help. There should then be an help for each action available on the desktop. [19:45] "Adding, Removing and Updating Applications" => "What are restricted and non-free software?" [19:46] Does anyone care about that topic? Has anyone ever read it? [19:46] and why would it be under that section to begin with.... [19:46] DougieRichardson: do you mean a task-based approach? [19:46] philbull: yes, but more structured and defined [19:47] philbull: this would integrate with DITA and building simple tools (because a standard format could be used) [19:48] it could also mean a form of error checking. [19:49] * DougieRichardson draws breath and surveys the silence [19:49] :) [19:49] sorry, had to get the washing in! [19:49] back now [19:49] bueller? bueller? [19:50] DougieRichardson: I'm interested in doing lots more user testing [19:50] I'm certainly in favor of topic-based authoring, as opposed to menu-based [19:50] we should use this to inform the way we write [19:50] philbull: regarding your 'restricted & non-free' comment, i have had new users who think that 'non-free' means that they have to pay for the software. [19:50] philbull: me to but we need to accept that if its visible, we need to explain it [19:51] not necessarily [19:51] free is the most misunderstood word in OSS [19:51] some things are obvious [19:51] some things, people don't care about [19:51] try out the docs on non linux users in the family [19:51] mwcrowley: exactly [19:51] I wish RMS had chosen to use something else [19:53] philbull: it sounds like you have a decent idea of what you had in mind with regards to planning... were you thinking of putting those notes up on the wiki? [19:53] that would probably be helpful. [19:53] one other thing on planning [19:53] j1mc: yes, will do [19:53] we should make a better appreciation of timing [19:53] DougieRichardson: how so? [19:53] are you thinking about this planning just for system docs and guides, or the wiki itself? [19:53] describing everything is the approach taken in the gnome manuals, that are going to be rewritten. [19:53] technomensch: good question [19:54] like the old thirds (planning) to one third (execution) idea. Otherwise we spend cycles discussing changes and not implementing [19:54] shaunm: any comment on dsas_'s note above? [19:55] dsas_:describing != documenting, even if its just a pointer to another area, a user should never not know what the button they are looking at does. [19:55] DougieRichardson: I'm not convinced that users will actually read that sort of documentation [19:55] they *should*, perhaps... [19:56] but I don't think that they will [19:56] i've looked at apple's docs... they mostly just have screenshots with arrows pointing to the different buttons. :) [19:56] but that's apple for you. :) [19:56] This is where a style guide would be useful. Perhaps the installation style guide to be created can become a more general style guide. [19:56] apple only does it one way though [19:57] the IG style guide should *not* be a general style guide [19:57] there are other styleguide efforts going on [19:57] see http://writingopensource.com/node/14 [19:57] here's a question.....this "style guide"...... [19:57] avi1: you make a decent point, though, in that this is a style consideration. [19:58] are we talking about "writing styles" such as "how to refer to certain things that have a variety of different terms?" [19:58] we're kind of getting off topic, though... [19:58] there is style guide, installation guide, wiki guide [19:58] too many guides in the kitchen [19:58] technomensch: see my link above [19:59] the WOS styleguide should be able to solve this problem [19:59] but it's not written yet [19:59] it probably would be a big help in my writing of the playbook [20:00] there are several things I keep flip-flopping about what to present, and how to present it [20:00] given that we've been here for an hour now, can we table the style discussion for now? [20:01] i guess it's kind of its own animal [20:01] philbull: you'll put your planning notes up on the wiki? [20:01] j1mc: sorry, I'm in an out, working on build stuff. asking for a comment on gnome's approach of describing everything? [20:01] j1mc: agreed [20:01] shaunm: yeah - what about it didn't work? [20:01] I think there's general agreement in the gnome docs community that our docs suck [20:02] j1mc: it's just not useful [20:02] everything gets described, but no real questions get answered [20:03] thanks, shaunm [20:03] moving on for now, then... wiki playbook & Hardware Database Documentation Connectivity [20:03] j1mc: shall we push on? [20:04] well, the wiki playbook has kinda weaved its way into multiple items from this meeting, so I guess it's fairly appropriate [20:04] has everyone at least gotten my link to view it through google docs? [20:04] technomensch: can you approve my access? [20:04] check your inbox [20:04] technomensch: I don't seem to have one [20:05] philbull: check the wiki [20:05] there's a link from the meeting agenda [20:05] done [20:06] access granted [20:06] OK, thanks. I've requested access [20:07] * DougieRichardson clicky clicky [20:07] technomensch: this looks really good. :) [20:07] done [20:07] thanks....still needs some work [20:08] and I really need to fine tune a way to showcase how to "categorize" new and existing articles [20:08] i like how it includes both content considerations and syntax help on one page so that everything is available in one spot. [20:08] that was the plan.... [20:08] I like that [20:08] I am trying to do away with the multiple pages.... [20:09] awesome, nice work technomensch [20:09] when it goes into a PDF, I'll try to add bookmarks to each section [20:09] split it [20:09] how so dougie? [20:09] so that the document link doesn't get lost after the meeting agenda changes: http://docs.google.com/Doc?id=dfm5m8jn_15gx7ttgd3&invite= [20:09] one for those who want to make a change (the first time occasional user) [20:09] one for those getting more regularly involved. [20:10] I think that those wanting to look for a specific method should be able to use the "Find' in either pdf or odt [20:10] i don't know... i think that having it all together might be more helpful. [20:10] just my 0.05 [20:10] that is my thinking j1 [20:11] in actuality, this whole playbook comes from my frustration during MY work on the wiki [20:11] if there's difficulty in condensing it to a single sheet. [20:11] thinking of how I'd like to see the docs [20:11] well, how about this dougie? [20:11] one cheatsheet for formatting wiki docs [20:12] and one cheat sheet for wiki structure, like the tags, creating new pages [20:12] DougieRichardson: ok. if the size of the doc gets cumbersome... then, yeah, split it up. [20:12] categorizing, etc.... [20:12] would this be acceptable for everyone? [20:12] yeah that seems about right Marc [20:12] technomensch, I've requested access to the playbook but can't get it yet [20:13] BrunoXLambert: did you get a look at the file? [20:13] mwcrowley: what about you? :) [20:13] technomensch, working now, thanks [20:13] just approved 2 more [20:14] I like this. using google docs for this type of collaboration does actually make sense [20:14] technomensch: if people have comments or suggestions, should they just post them to the mailing list? [20:14] yes, please. [20:14] well, jim, you phil, and dougie have been collaborator access [20:15] ok... for anyone who wasn't able to attend today, pls request access to the google doc, and post any comments or suggestions. [20:15] so if you need to make a glaring change, feel free [20:15] technomensch: thanks [20:15] everyone else post to the mailing list [20:15] cheers Marc, I'll probably mail you though ;-) [20:15] j1mc, asked access for it now [20:15] technomensch: on to the Hardware Database topic? [20:16] well, it's kinda self explainatory. this was more just to keep everyone in the loop [20:16] BrunoXLambert: cool. as a new member of the team, please let us know if this is helpful, or if you find that you still need help with some items [20:16] yes, definitely [20:16] it would be good to get a fresh perspective [20:17] * DougieRichardson really likes Dropbox [20:17] for future reference, here's the link to the speck about the hardware database topic: https://wiki.ubuntu.com/specs/KernelKarmicHWdbWorkshop [20:17] ok... on to new business? [20:17] well [20:17] there is one item [20:17] ok [20:17] about that [20:18] and that is the part where they say they don't have enough manpower [20:18] to create a web front end once the api is available [20:18] if we have a good webdesigner, it might be nice to have something we can show/propose to them [20:18] kinda get a headstart on it [20:18] we could if someone would upload the front page... [20:19] * DougieRichardson good humoured dig at mdke [20:19] What is the proposed API [20:19] technomensch: Might be worth asking on ubuntu-website to get a web front end person in [20:20] ok, thanks for the suggestion. [20:20] great idea [20:20] dsas_ technomensch I agree - I know I haven't the time [20:20] neither do I. [20:20] even if I did have the skillz [20:21] ok... anything else on this for now? do we have any action-item take-aways for this? [20:21] anything to be done? [20:21] not for now [20:22] ok - technomensch, i guess you'll keep us updated if things change? [20:23] ::nod:: [20:23] ok... next topic then [20:23] DITA and Mallard [20:23] I wish that mdke and dinda were able to make this meeting [20:23] but i'll just jump into a quick mention of DITA [20:24] as a reference, here are a couple of links about the technical side of DITA: [20:24] the architectural specification: http://docs.oasis-open.org/dita/v1.1/OS/archspec/archspec.html [20:24] the language specification: http://docs.oasis-open.org/dita/v1.1/CS01/langspec/ditaref-type.html [20:24] i've been looking those over, and there's a lot to digest. [20:24] but basically... why would we consider using DITA? [20:25] DITA has a lot of uptake in the professional tech writing community, it's an open source project, and it allows for content re-use and conditional text. [20:26] conditional text being... you can create one document and include text specific to kubuntu, ubuntu, and xubuntu... and then generate flavor-specific docs from that one doc set. [20:26] (if that makes sense) [20:26] thing is... it's a new toolchain (using ANT build files...), no other distros use it currently... [20:27] * DougieRichardson nods [20:27] aren't we stuck with using whatever yelp supports? [20:27] would introduce an additional syntax for new users to learn. [20:27] dsas_: well, the yelp developer is in on this meeting now (shaunm) [20:27] dsas_ dita can be used to generate docbook [20:27] he knows about it [20:28] so . . . i have an interest in it, and dinda has expressed an interest in it, but i'm not sure how feasible it is for this release. it's not even packaged in ubuntu yet [20:28] Its not feasible for Karmic. [20:29] yeah [20:29] It is a good idea however and should probably be something we invest time in [20:29] but ... with regards to the Learning Team... being able to share content across the official docs, the learning team, and the training team (canonical training stuff...) [20:29] that would be helpful. [20:30] I read the specs (thanks Jim), we should consider investigating this more thouroughly [20:30] I started looking into what it would take to do dita->mallard, which I think would give a more faithful representation of dita than dita->docbook [20:30] but I'm pressed for time, and I can't make that a top priority right now [20:30] shaunm: understood. (focus!) :-) [20:31] heh [20:31] shaunm: mallard information seems a little, sparse at the moment - what time frame are you guys working to [20:31] ok... so... for this release, i'll just see about getting it packaged into ubuntu [20:31] "it" being DITA [20:31] j1mc: packaging it isn't a major issue [20:31] so if you really want to pursue dita in yelp, there are three possible approaches: dita->docbook, dita->mallard, or dita support directly in yelp [20:32] DougieRichardson: the spec isn't fully fleshed out, but I don't consider the existing functionality at all sparse [20:32] philbull: any comments on DITA for now? [20:32] shaunm: don't take offense, from Gnome.org it does [20:32] I know j1mc has asked about profiling. what else are people interested in that isn't there? [20:32] DougieRichardson: wasn't offended [20:33] shaunm: "profiling"? could you explain a bit more about that? [20:33] j1mc: not from me yet [20:33] just wondering what things people need [20:33] j1mc: sorry, profiling == conditional processing [20:33] no idea why people call it profiling, but they do [20:33] :) [20:33] probably something to do with tailoring a document to different profiles or something [20:34] ok... seeing as we're already kind of doing it, we'll officially move on to discussing Mallard [20:34] oh sorry, didn't mean to hijack the conversation [20:34] here's a link the language specification for it: http://www.gnome.org/~shaunm/mallard/spec.html [20:34] np [20:34] I had some notes, but to save time: [20:34] http://philbull.googlepages.com/MALLARD.txt [20:34] shaunm: how automated can the conditioning be? Take UNR, can we in some way allow the help to identify which interface is in use? [20:36] philbull: that's a pretty good summary. thanks. [20:36] ok, so conditional processing. typically, formats provide loose semantics on this, and people use their own tailored processing tools to do exactly the conditional processing they need, at build time [20:36] that would be extremely cool if it could dougie [20:36] we display source documents in yelp, at run time [20:37] which means for me to do conditional processing, I need very exactly specified behavior [20:37] note that yelp doesn't do any conditional processing on docbook files, and people have been doing conditional processing for years [20:38] also, what's UNR? [20:38] ubuntu netbook remix [20:38] ubuntu netbook remox [20:38] (be patient with me. I don't know all the ubuntu lingo) [20:38] in s t e r e o ;-) [20:38] :) [20:38] heh [20:38] sorry, I've got to run, but I'll stay in contact, [20:38] mwcrowley: thanks for sticking around :) [20:39] so it might just be that build-time conditional processing is sufficient for you [20:39] ubuntu/gnome with a different launcher, different default apps and some window management stuff [20:39]