Ubuntu Wiki

This is the log for the 27 June 2009 DocumentationTeam meeting.

19:04   j1mc    Meeting Agenda is up at: https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda
19:04   technomensch    j1,  I'm trying to recall.  whats your wiki id?
19:05   j1mc    https://wiki.ubuntu.com/j1mc
19:05   technomensch    ah.......
19:06   j1mc    ok, i know it's a small group here today, but we can still cover some items.
19:06   j1mc    we'll try to be brief.
19:06   philbull        he he, no chance
19:06   j1mc    first - is anyone here new to the group?
19:06   mwcrowley       I'm new
19:06   j1mc    hi mwcrowley
19:07   mwcrowley       hi all
19:07   j1mc    care to briefly introduce yourself?
19:07   technomensch    wait
19:07   technomensch    j1
19:07   technomensch    want to start the meeting bot?
19:07   BrunoXLambert   I am new there
19:07   minderaser      I'm new as well
19:07   j1mc    technomensch: let's not worry aboutit.
19:08   philbull        welcome, guys!
19:08   j1mc    if you are new... welcome. :)
19:08   j1mc    please just go ahead and introduce yourself in a sentence or two. :)
19:08   mwcrowley       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   j1mc    coolness.
19:09   j1mc    others?  don't be shy. :)
19:09   BrunoXLambert   I'm usung ubuntu since breezy. working at Revolution Linux with stgraber. I'm a support and trainnign guy
19:09   j1mc    awesome. :)
19:09   minderaser      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   j1mc    great. :)
19:10   avi1    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   j1mc    cool... welcome, avi1
* DougieRichardson waves to j1mc - kids needed feeding
19:11   j1mc    DougieRichardson: o/
19:11   missaugustina   I'm Augustina! I've been active on the list but this is my first meeting.
19:11   technomensch    welcome
19:11   j1mc    great! lots of new people.
19:11   technomensch    glad you could make it
19:11   j1mc    anyone else?
* DougieRichardson o/
19:12   technomensch    missaugstina, don't worry, this is only the second meeting we've had within the last few months.....
19:12   j1mc    someone had mentioned that they wanted to know different ways people could get involved w/ the project.
19:12   j1mc    some info is here: https://wiki.ubuntu.com/DocumentationTeam/Organization
19:13   j1mc    but chances are, if you're at this meeting, you're already familiar with some of what we do.
19:13   j1mc    but you can get involved through the system documentation, work on the wiki, and even work on translations.
19:13   technomensch    or any of the many guides such as the server guide
19:14   j1mc    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   j1mc    did anyone have any particular questions for now?
19:15   technomensch    j1, I propose a secondary meeting to educate on launchpad and bzr....etc...., maybe a mini-class
19:15   shankhs hi
19:15   mwcrowley       mini-class would be good
19:16   DougieRichardson        what about the one from the openweek?
19:16   j1mc    technomensch: cool - we had an ubuntu open week session that covered a lot of stuff from bzr and launchpad.
19:16   j1mc    DougieRichardson: right
19:16   BrunoXLambert   I'm in for a mini-class
19:16   mwcrowley       any suggestions for a best first step.  Are there any areas that need immediate help?
19:16   technomensch    the problem with open week, are the international times
19:17   DougieRichardson        technomensch: doesn't stop us reusing the material though ;-)
19:17   j1mc    here's a log of our session on bzr: https://wiki.ubuntu.com/MeetingLogs/openweekJaunty/DocsBzr
19:17   j1mc    and here's the log of the session on docbook: https://wiki.ubuntu.com/MeetingLogs/openweekJaunty/DocsDocbook
19:17   technomensch    those are good enough for me :)
19:18   j1mc    emmajane did a good job with the docbook, and the bzr session was really good, too.
19:18   j1mc    anything else for now?
* DougieRichardson shakes head
19:19   mwcrowley       those links are a good place to start.
19:19   shaunm  j1mc: sorry, are you going through an agenda?
19:19   philbull        https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda
19:20   j1mc    shaunm: https://wiki.ubuntu.com/DocumentationTeam/MeetingAgenda
19:20   j1mc    agenda ^^
19:20   shaunm  gracias
19:20   j1mc    on to "Ye Olde Business"
19:20   j1mc    someone put up, "How best to collaborate with translators"
19:20   j1mc    but I think that might be a meeting topic on its own.
19:21   j1mc    or, worthy of a meeting on its own... thoughts?
19:22   DougieRichardson        I wasn't aware there were any issues with translations at the moment?
19:23   philbull        if no-one has any specific issues we should move on
* DougieRichardson nods
19:23   j1mc    Maybe it would be better to talk about this when Milo or some of the other translation folks are present.
19:23   j1mc    yeah
19:24   j1mc    DougieRichardson: anything on the Learning Initiative?
19:24   DougieRichardson        j1mc: not really no, they're still quite focussed on structure
19:25   DougieRichardson        they also keep holding meetings at really inconvenient times!
19:25   j1mc    :)  "structure" being the documentation structure, or . . . something else?
19:25   DougieRichardson        I think we need to look at the project and see how it suits us
19:25   philbull        do you have any links?
19:25   DougieRichardson        j1mc: team structure
19:25   philbull        I'm not familiar with this
19:25   DougieRichardson        philbull: yes wait one
19:26   DougieRichardson        https://wiki.ubuntu.com/Learning
19:26   DougieRichardson        sabdfl is very enthusiastic
19:27   DougieRichardson        initially it looked to integrate with the idea of classrooms/tutorials and so on quite well, its in Moodle
19:28   technomensch    I've been wanting to learn moodle, so I wouldn't mind getting involved with that
19:28   j1mc    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   DougieRichardson        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   DougieRichardson        j1mc:they want active participation
19:29   philbull        any word on integration with the docs?
19:29   missaugustina   I'm particularly interested in helping out with the Developer Documentation/tutorials since there seems to be a lack of it
19:29   philbull        training material goes alongside help resources
19:29   DougieRichardson        philbull: in what way?
19:29   philbull        well, via h.u.c or via links in Yelp?
19:29   DougieRichardson        I envisaged it as being a resource to train our members
19:30   DougieRichardson        there's no reason not to be able to integrate it in some way in that respect.
19:30   philbull        I was thinking more to do with the "How to use Ubuntu" bit
19:30   philbull        (i.e. for users)
19:30   DougieRichardson        I know, mdke was quite concerned with duplication of effort
* j1mc nods
19:31   philbull        there are lots of user assistance type projects floating around ubuntu at the moment
19:31   DougieRichardson        If I'm honest, I think the project might be a little ambitious and I have concerns about that section
19:31   philbull        we perhaps need to communicate with other initiatives more
19:31   j1mc    missaugustina: have you seen the MOTU/GettingStarted wiki documentation?
19:31   j1mc    missaugustina: https://wiki.ubuntu.com/MOTU/GettingStarted
19:32   DougieRichardson        motu are also involved in this initiative, although I haven't heard anything from them
19:32   j1mc    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   technomensch    query:  would these be using the playbooks we're working on?
19:33   DougieRichardson        technomensch: possibly
19:33   j1mc    missaugustina: you may also want to touch base with Nathan Handler (nhandler), as he has been doing some work on developer documentation.
19:34   DougieRichardson        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   technomensch    that would be quite an ambitious project
19:35   DougieRichardson        I have worries
19:36   technomensch    I thiink that would be an understatement doug
19:36   j1mc    it looks like i need to read through their meeting logs and mailing list to see what they're up to.
19:36   DougieRichardson        1. there's a heavy forums influence on the project
19:36   DougieRichardson        2. it duplicates, or has the potential to duplicate our efforts
19:36   DougieRichardson        3. moodle / docbook integration needs work
19:37   philbull        DocBook? Why DocBook?
19:37   DougieRichardson        I think really, we  need to read over all their logs and discuss it on list
19:37   j1mc    can we decide on any action items concerning this for now?
19:37   DougieRichardson        Does anyone have any concerns?
19:37   philbull        Yep, I'd like to discuss this more on the list
19:38   DougieRichardson        philbull: because we use docbook and they use moodle
19:38   j1mc    philbull: yeah, same here.
19:38   DougieRichardson        philbull: ^-^
19:38   philbull        DougieRichardson: Ah, gotcha
19:39   philbull        OK, next item?
19:39   j1mc    sure
19:39   j1mc    that's you, phil: "introducing rigorous planning as a requirement..."
19:40   technomensch    talk about a mouthful
19:40   philbull        Yes. I think that we should start planning things properly before we start writing them
19:40   technomensch    second
19:40   avi1    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   philbull        I don't think that we do that enough at the moment
19:40   avi1    including reusable content b/w teams
19:40   DougieRichardson        we need to discuss DITA seperately.
19:41   avi1    ok, just keep this in mind for that discussion
19:41   philbull        I'm using the Installation Guide as a bit of a test run for more intensive planning/design
19:42   j1mc    philbull: do you have any references that you can point us to for what you had in mind about doc planning?
19:42   philbull        Well, Lynda's stuff from WOSCON is useful
19:42   philbull        I should post it somewhere
19:42   j1mc    that would be helpful
19:43   philbull        It doesn't have to be anything fancy
19:43   philbull        Just as long as we make sure that what we're writing is suitable and useful for our users...
19:43   philbull        ...before we write it.
19:44   DougieRichardson        are we talking about managing resources or defining prior to encoding?
19:44   philbull        For example, most of the topics in the system docs were added because they seemed like a good idea to the author
19:44   technomensch    in otherwords, outlining and brainstorming, and maybe psydocoding....
19:45   philbull        Pretty much. We should have a structure and a design brief in place before we produce any content
19:45   philbull        Look at the system docs
19:45   DougieRichardson        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   philbull        "Adding, Removing and Updating Applications" => "What are restricted and non-free software?"
19:46   philbull        Does anyone care about that topic? Has anyone ever read it?
19:46   technomensch    and why would it be under that section to begin with....
19:46   philbull        DougieRichardson: do you mean a task-based approach?
19:46   DougieRichardson        philbull: yes, but more structured and defined
19:47   DougieRichardson        philbull: this would integrate with DITA and building simple tools (because a standard format could be used)
19:48   DougieRichardson        it could also mean a form of error checking.
* DougieRichardson draws breath and surveys the silence
19:49   j1mc    :)
19:49   philbull        sorry, had to get the washing in!
19:49   philbull        back now
19:49   technomensch    bueller?  bueller?
19:50   philbull        DougieRichardson: I'm interested in doing lots more user testing
19:50   avi1    I'm certainly in favor of topic-based authoring, as opposed to menu-based
19:50   philbull        we should use this to inform the way we write
19:50   j1mc    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   DougieRichardson        philbull: me to but we need to accept that if its visible, we need to explain it
19:51   philbull        not necessarily
19:51   DougieRichardson        free is the most misunderstood word in OSS
19:51   philbull        some things are obvious
19:51   philbull        some things, people don't care about
19:51   mwcrowley       try out the docs on non linux users in the family
19:51   philbull        mwcrowley: exactly
19:51   DougieRichardson        I wish RMS had chosen to use something else
19:53   j1mc    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   j1mc    that would probably be helpful.
19:53   DougieRichardson        one other thing on planning
19:53   philbull        j1mc: yes, will do
19:53   DougieRichardson        we should make a better appreciation of timing
19:53   philbull        DougieRichardson: how so?
19:53   technomensch    are you thinking about this planning just for system docs and guides, or the wiki itself?
19:53   dsas_   describing everything is the approach taken in the gnome manuals, that are going to be rewritten.
19:53   j1mc    technomensch: good question
19:54   DougieRichardson        like the old thirds (planning) to one third (execution) idea.  Otherwise we spend cycles discussing changes and not implementing
19:54   j1mc    shaunm: any comment on dsas_'s note above?
19:55   DougieRichardson        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   philbull        DougieRichardson: I'm not convinced that users will actually read that sort of documentation
19:55   philbull        they *should*, perhaps...
19:56   philbull        but I don't think that they will
19:56   j1mc    i've looked at apple's docs... they mostly just have screenshots with arrows pointing to the different buttons. :)
19:56   j1mc    but that's apple for you. :)
19:56   avi1    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   DougieRichardson        apple only does it one way though
19:57   philbull        the IG style guide should *not* be a general style guide
19:57   philbull        there are other styleguide efforts going on
19:57   philbull        see http://writingopensource.com/node/14
19:57   technomensch    here's a question.....this "style guide"......
19:57   j1mc    avi1: you make a decent point, though, in that this is a style consideration.
19:58   technomensch    are we talking about "writing styles" such as "how to refer to certain things that have a variety of different terms?"
19:58   j1mc    we're kind of getting off topic, though...
19:58   technomensch    there is style guide, installation guide, wiki guide
19:58   technomensch    too many guides in the kitchen
19:58   philbull        technomensch: see my link above
19:59   philbull        the WOS styleguide should be able to solve this problem
19:59   philbull        but it's not written yet
19:59   technomensch    it probably would be a big help in my writing of the playbook
20:00   technomensch    there are several things I keep flip-flopping about what to present, and how to present it
20:00   j1mc    given that we've been here for an hour now, can we table the style discussion for now?
20:01   j1mc    i guess it's kind of its own animal
20:01   j1mc    philbull: you'll put your planning notes up on the wiki?
20:01   shaunm  j1mc: sorry, I'm in an out, working on build stuff.  asking for a comment on gnome's approach of describing everything?
20:01   philbull        j1mc: agreed
20:01   j1mc    shaunm: yeah - what about it didn't work?
20:01   shaunm  I think there's general agreement in the gnome docs community that our docs suck
20:02   shaunm  j1mc: it's just not useful
20:02   shaunm  everything gets described, but no real questions get answered
20:03   j1mc    thanks, shaunm
20:03   j1mc    moving on for now, then... wiki playbook & Hardware Database Documentation Connectivity
20:03   philbull        j1mc: shall we push on?
20:04   technomensch    well, the wiki playbook has kinda weaved its way into multiple items from this meeting, so I guess it's fairly appropriate
20:04   technomensch    has everyone at least gotten my link to view it through google docs?
20:04   j1mc    technomensch: can you approve my access?
20:04   j1mc    check your inbox
20:04   philbull        technomensch: I don't seem to have one
20:05   j1mc    philbull: check the wiki
20:05   j1mc    there's a link from the meeting agenda
20:05   technomensch    done
20:06   technomensch    access granted
20:06   philbull        OK, thanks. I've requested access
* DougieRichardson clicky clicky
20:07   j1mc    technomensch: this looks really good. :)
20:07   technomensch    done
20:07   technomensch    thanks....still needs some work
20:08   technomensch    and I really need to fine tune a way to showcase how to "categorize" new and existing articles
20:08   j1mc    i like how it includes both content considerations and syntax help on one page so that everything is available in one spot.
20:08   technomensch    that was the plan....
20:08   DougieRichardson        I like that
20:08   technomensch    I am trying to do away with the multiple pages....
20:09   philbull        awesome, nice work technomensch
20:09   technomensch    when it goes into a PDF, I'll try to add bookmarks to each section
20:09   DougieRichardson        split it
20:09   technomensch    how so dougie?
20:09   j1mc    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   DougieRichardson        one for those who want to make a change (the first time occasional user)
20:09   DougieRichardson        one for those getting more regularly involved.
20:10   technomensch    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   j1mc    i don't know... i think that having it all together might be more helpful.
20:10   DougieRichardson        just my 0.05
20:10   technomensch    that is my thinking j1
20:11   technomensch    in actuality, this whole playbook comes from my frustration during MY work on the wiki
20:11   DougieRichardson        if there's difficulty in condensing it to a single sheet.
20:11   technomensch    thinking of how I'd like to see the docs
20:11   technomensch    well, how about this dougie?
20:11   technomensch    one cheatsheet for formatting wiki docs
20:12   technomensch    and one cheat sheet for wiki structure, like the tags, creating new pages
20:12   j1mc    DougieRichardson: ok.  if the size of the doc gets cumbersome... then, yeah, split it up.
20:12   technomensch    categorizing, etc....
20:12   technomensch    would this be acceptable for everyone?
20:12   DougieRichardson        yeah that seems about right Marc
20:12   minderaser      technomensch, I've requested access to the playbook but can't get it yet
20:13   j1mc    BrunoXLambert: did you get a look at the file?
20:13   j1mc    mwcrowley: what about you?  :)
20:13   minderaser      technomensch, working now, thanks
20:13   technomensch    just approved 2 more
20:14   technomensch    I like this.  using google docs for this type of collaboration does actually make sense
20:14   j1mc    technomensch: if people have comments or suggestions, should they just post them to the mailing list?
20:14   technomensch    yes, please.
20:14   technomensch    well, jim, you phil, and dougie have been collaborator access
20:15   j1mc    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   technomensch    so if you need to make a glaring change, feel free
20:15   j1mc    technomensch: thanks
20:15   technomensch    everyone else post to the mailing list
20:15   DougieRichardson        cheers Marc, I'll probably mail you though ;-)
20:15   BrunoXLambert   j1mc, asked access for it now
20:15   j1mc    technomensch: on to the Hardware Database topic?
20:16   technomensch    well, it's kinda self explainatory.  this was more just to keep everyone in the loop
20:16   j1mc    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   technomensch    yes, definitely
20:16   technomensch    it would be good to get a fresh perspective
* DougieRichardson really likes Dropbox
20:17   j1mc    for future reference, here's the link to the speck about the hardware database topic: https://wiki.ubuntu.com/specs/KernelKarmicHWdbWorkshop
20:17   j1mc    ok... on to new business?
20:17   technomensch    well
20:17   technomensch    there is one item
20:17   j1mc    ok
20:17   technomensch    about that
20:18   technomensch    and that is the part where they say they don't have enough manpower
20:18   technomensch    to create a web front end once the api is available
20:18   technomensch    if we have a good webdesigner, it might be nice to have something we can show/propose to them
20:18   technomensch    kinda get a headstart on it
20:18   DougieRichardson        we could if someone would upload the front page...
* DougieRichardson good humoured dig at mdke
20:19   DougieRichardson        What is the proposed API
20:19   dsas_   technomensch: Might be worth asking on ubuntu-website to get a web front end person in
20:20   technomensch    ok, thanks for the suggestion.
20:20   technomensch    great idea
20:20   DougieRichardson        dsas_ technomensch I agree - I know I haven't the time
20:20   technomensch    neither do I.
20:20   technomensch    even if I did have the skillz
20:21   j1mc    ok... anything else on this for now? do we have any action-item take-aways for this?
20:21   j1mc    anything to be done?
20:21   DougieRichardson        not for now
20:22   j1mc    ok - technomensch, i guess you'll keep us updated if things change?
20:23   technomensch    ::nod::
20:23   j1mc    ok... next topic then
20:23   j1mc    DITA and Mallard
20:23   j1mc    I wish that mdke and dinda were able to make this meeting
20:23   j1mc    but i'll just jump into a quick mention of DITA
20:24   j1mc    as a reference, here are a couple of links about the technical side of DITA:
20:24   j1mc    the architectural specification: http://docs.oasis-open.org/dita/v1.1/OS/archspec/archspec.html
20:24   j1mc    the language specification: http://docs.oasis-open.org/dita/v1.1/CS01/langspec/ditaref-type.html
20:24   j1mc    i've been looking those over, and there's a lot to digest.
20:24   j1mc    but basically... why would we consider using DITA?
20:25   j1mc    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   j1mc    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   j1mc    (if that makes sense)
20:26   j1mc    thing is... it's a new toolchain (using ANT build files...), no other distros use it currently...
* DougieRichardson nods
20:27   dsas_   aren't we stuck with using whatever yelp supports?
20:27   j1mc    would introduce an additional syntax for new users to learn.
20:27   j1mc    dsas_: well, the yelp developer is in on this meeting now (shaunm)
20:27   DougieRichardson        dsas_ dita can be used to generate docbook
20:27   j1mc    he knows about it
20:28   j1mc    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   DougieRichardson        Its not feasible for Karmic.
20:29   j1mc    yeah
20:29   DougieRichardson        It is a good idea however and should probably be something we invest time in
20:29   j1mc    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   j1mc    that would be helpful.
20:30   DougieRichardson        I read the specs (thanks Jim), we should consider investigating this more thouroughly
20:30   shaunm  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   shaunm  but I'm pressed for time, and I can't make that a top priority right now
20:30   j1mc    shaunm: understood.  (focus!) :-)
20:31   shaunm  heh
20:31   DougieRichardson        shaunm: mallard information seems a little, sparse at the moment - what time frame are you guys working to
20:31   j1mc    ok... so... for this release, i'll just see about getting it packaged into ubuntu
20:31   j1mc    "it" being DITA
20:31   DougieRichardson        j1mc: packaging it isn't a major issue
20:31   shaunm  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   shaunm  DougieRichardson: the spec isn't fully fleshed out, but I don't consider the existing functionality at all sparse
20:32   j1mc    philbull: any comments on DITA for now?
20:32   DougieRichardson        shaunm: don't take offense, from Gnome.org it does
20:32   shaunm  I know j1mc has asked about profiling.  what else are people interested in that isn't there?
20:32   shaunm  DougieRichardson: wasn't offended
20:33   j1mc    shaunm: "profiling"? could you explain a bit more about that?
20:33   philbull        j1mc: not from me yet
20:33   shaunm  just wondering what things people need
20:33   shaunm  j1mc: sorry, profiling == conditional processing
20:33   shaunm  no idea why people call it profiling, but they do
20:33   j1mc    :)
20:33   shaunm  probably something to do with tailoring a document to different profiles or something
20:34   j1mc    ok... seeing as we're already kind of doing it, we'll officially move on to discussing Mallard
20:34   shaunm  oh sorry, didn't mean to hijack the conversation
20:34   j1mc    here's a link the language specification for it: http://www.gnome.org/~shaunm/mallard/spec.html
20:34   j1mc    np
20:34   philbull        I had some notes, but to save time:
20:34   philbull        http://philbull.googlepages.com/MALLARD.txt
20:34   DougieRichardson        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   j1mc    philbull: that's a pretty good summary. thanks.
20:36   shaunm  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   technomensch    that would be extremely cool if it could dougie
20:36   shaunm  we display source documents in yelp, at run time
20:37   shaunm  which means for me to do conditional processing, I need very exactly specified behavior
20:37   shaunm  note that yelp doesn't do any conditional processing on docbook files, and people have been doing conditional processing for years
20:38   shaunm  also, what's UNR?
20:38   j1mc    ubuntu netbook remix
20:38   DougieRichardson        ubuntu netbook remox
20:38   shaunm  (be patient with me.  I don't know all the ubuntu lingo)
20:38   DougieRichardson        in s t e r e o ;-)
20:38   j1mc    :)
20:38   shaunm  heh
20:38   mwcrowley       sorry, I've got to run, but I'll stay in contact,
20:38   j1mc    mwcrowley: thanks for sticking around :)
20:39   shaunm  so it might just be that build-time conditional processing is sufficient for you
20:39   dsas_   ubuntu/gnome with a different launcher, different default apps and some window management stuff
20:39   shaunm  i.e. you install pages with conditional information stripped.  yelp does nothing special.  at build time, you construct the pages based on conditions in a source page file
20:40   j1mc    shaunm: from your perspective, what are the "missing features" in mallard that are needed for you to say, "this is ready to use."
20:40   DougieRichardson        UNR has two interfaces that a user can switch between at runtime
20:40   j1mc    philbull mentioned i18n and "other missing features"
20:41   shaunm  j1mc: the schema as it exists right now is more or less what I'm planning to be 1.0
20:41   j1mc    even if not all of the "nice to haves" are in place...
20:41   shaunm  I need to flesh out the spec and the implementation
20:42   j1mc    for those who aren't at the meeting now, or for those completely new to mallard - do you have a link to the spec / implementation info?
20:43   shaunm  http://www.gnome.org/~shaunm/mallard/
20:43   shaunm  http://www.gnome.org/~shaunm/mallard/mallard.rng
20:43   shaunm  (or .rnc if you want the compact syntax)
20:44   j1mc    cool
20:44   j1mc    philbull: did you have any other comments you wanted to make at this time?
20:44   shaunm  note that the spec itself is written in mallard, so you're looking at example html build from mallard
20:44   j1mc    w00t
20:45   shaunm  so...
20:45   philbull        not really, most of it should be in that summary I posted
20:45   shaunm  I'm planning for the spec to be 1.0 for gnome 3.0
20:45   shaunm  I have a short list of things I'm planning for 1.2, which I intend to release six months later with gnome 3.2
20:46   dsas_   which is march 2010?
20:46   shaunm  (the spec version won't always increment with gnome releases)
20:46   shaunm  dsas_: tentatively, yes
20:46   j1mc    ok.  thanks shaunm :)
20:47   shaunm  conditional processing could be on the 1.2 list, if I can get some people to sit down with me and hammer out concrete details
20:47   technomensch    <<< is kinda glad he's sticking on the wiki side of things for a while
20:48   j1mc    if people wanted to learn more about this schema stuff... where could they look?  i mean, to learn about how schemas are set up...
20:48   j1mc    is it xml stuff?  xsl?  schema-o-rama.com?
20:49   shaunm  relax-ng
* j1mc goes to register schema-o-rama.com :)
20:49   j1mc    ok... cool.
20:49   j1mc    philbull: installation guide!
20:49   shaunm  if there's demand, I don't mind creating an xsd as well.  but the rng is canonical
20:49   j1mc    canonical with a lowercase "c" :)
20:50   shaunm  heh, yes
20:50   philbull        OK, installation guide:
20:50   philbull        The Installation Guide (IG) team was selected this week.
20:50   philbull        We have a great bunch of people, and I'm really excited about the project.
20:50   philbull        It's a much more structured approach to running a docs project than I'm used to, so we'll see how it goes.
20:50   philbull        A list of the members of the team is available at:
20:50   philbull        https://wiki.ubuntu.com/Specs/KarmicInstallationGuide/TeamRoles
20:50   philbull        Jim and Dougie are also going to advise on what set of tools we should use to write the guide.
20:50   philbull        It may or may not be DITA or Mallard, depending on what seems the most feasible.
20:50   philbull        Next week we should hopefully start getting down to the nitty-gritty.
20:50   philbull        DB and the writers (Augustina, Avi and Kelvin) are sorting out a style guide.
20:50   philbull        Adam should be getting in touch with the ubiquity devs to get a roadmap out of them.
20:50   philbull        I think they're making a lot of changes this cycle, which will obviously affect us.
20:51   philbull        I've asked Nathan to look at planning a user testing programme.
20:51   philbull        User testing is a *big* deal to me at the moment. I think we should be doing it everywhere.
20:51   philbull        I have a few ideas on how we can extract information on usage patterns etc.
20:51   philbull        That's about it for the IG for now. Any questions/flames?
20:51   philbull        .
20:53   j1mc    thanks philbull
20:53   philbull        sorry for the massive textdump
20:53   j1mc    DougieRichardson: i sent a note to you and philbull ... i'm not feeling super hot about using DITA for this release of the guide.
20:54   DougieRichardson        j1mc: not if its for Karmic and ultimately, if we move to DITA then we would have to merge other documentation in any evnet
20:54   DougieRichardson        ^^event
20:54   philbull        j1mc: I'll get back to you about that tomorrow. I still need to get a test installation of the open toolkit working
20:54   DougieRichardson        philbull: the start scripts good isn't it. lol
20:55   philbull        heh
20:55   j1mc    the installation script installs it to the user's home directory
20:55   j1mc    opensuse packages it so that it goes into /usr/... something
20:55   DougieRichardson        once you take out the ^M carriage returns
20:56   j1mc    just in looking over the syntax, it would take time to decide which elements to use
20:56   j1mc    in what situations...
20:56   philbull        j1mc: we could just use a set similar to Mallard's
20:57   philbull        that would make conversion much easier
20:57   j1mc    i'd rather we prepare this version using known tools, then we could easily port it to DITA if we decide that's what we want to do later.
20:57   philbull        That seems reasonable
20:57   DougieRichardson        I'm in agreement
20:57   philbull        If we use DocBook, would you or Dougie mind helping me with the DocBook->PDF stuff?
20:58   philbull        My attempts always look like ass
20:58   philbull        I want the guide to be pretty!
20:58   j1mc    philbull: sure.  iirc, even mdke has some difficulty with converting to PDF
20:58   j1mc    opensuse uses a proprietary docbook > pdf converter called "renderx" (i think that's what it is called).
20:59   j1mc    i think it is generally known to produce prettier output
20:59   j1mc    :/
20:59   DougieRichardson        dblatex is not very configurable
20:59   DougieRichardson        the best we could manage is available in the desktop training branch
20:59   philbull        Maybe we can do DocBook->HTML->Layout tool
21:01   DougieRichardson        I'm beginning to lean to DB->ODF->PDF
21:01   philbull        That would be good too.
21:01   philbull        At least OO is scriptable
21:01   j1mc    i'm certainly willing to help with it, though
21:01   philbull        Thanks guys
21:01   philbull        Shall we move on?
21:02   technomensch    btw, semisidebar
21:02   j1mc    it sounds like, at this time, we're going to go ahead with docbook for the Install Guide then
21:02   technomensch    after I finish my guide, what am I going to do with it?
21:02   philbull        j1mc: agreed
21:02   technomensch    I mean the playbook
21:02   philbull        technomensch: we can attach a PDF to a page on the wiki
21:03   technomensch    quick, easy, simple
21:03   technomensch    I like it
21:03   j1mc    i think it should also be available (in some form) on the wiki itself
21:03   j1mc    ^^ referring to technomensch's document
21:04   philbull        technomensch: Google Docs can export to ODF, can't it?
21:04   j1mc    yes
21:04   j1mc    philbull: it can even save as pdf
21:05   technomensch    that was a project I was working on previously, trying to clean up all the formatting docs
21:05   philbull        awesome
21:05   technomensch    once I have this playbook, I think that it could almost replace the existing info
21:05   technomensch    eventually......
21:06   technomensch    I just figured this docbook discussion might be a good time to slip that question in :)
21:06   j1mc    ok... Kubuntu and Xubuntu
21:06   j1mc    I don't think anyone is here from Kubuntu
21:07   j1mc    and Xubuntu docs need a lot of lurve
21:07   j1mc    so I need to get my groove on
21:07   j1mc    that's all on that for now, I guess. :)
21:08   j1mc    well, I guess I'll say that I'm going to get a Xubunt team member to update our CSS for how our docs are displayed
21:08   j1mc    Next topic (almost done)
21:08   j1mc    Discussion about licensing for wiki.ubuntu.com
21:09   philbull        does it need licensing?
21:09   philbull        is anyone going to reuse any of the material there?
21:09   j1mc    mdke: sent a note to the ML about it.
21:09   j1mc    "The team wiki isn't licensed. I think that having been prompted by a
21:09   j1mc    blog posts around about this, the CC will address it soon."
21:10   j1mc    seeing as mdke is on the Community Council, we'll wait to hear how it is addressed.  If people have comments... we have a thread on the ML about the topic.
21:11   j1mc    i think my brain hurts
21:11   j1mc    last topic?
21:12   philbull        It's too big to discuss now
21:12   j1mc    ok
21:12   philbull        I'll bring it up on the ML
21:12   j1mc    sounds good
21:12   j1mc    any other comments before we wrap up?
21:14   j1mc    *crickets*
21:14   j1mc    ok, well, thanks for participating today, everyone