[00:20] hi billybigrigger [00:42] hi all [00:42] hello [00:43] Hey [00:43] xubuntu / xfce are considering documentation markup approaches [00:43] It looks very neat [00:44] looking at both GNOME's new "mallard" and python-docutils+sphinx [00:44] here's info about the markup in mallard: http://www.gnome.org/~shaunm/mallard/spec.html [00:45] i think if the documentating people are at all familiar to xml/xhtml, the mallard syntax looks better. [00:46] here's a sample of reStructureText+sphinx: http://pastebin.ubuntu.com/195983/ [00:47] mallard has a simpler markup than docbook, and scratches some itches for documentation writers [00:47] what about the (default) appearance of mallard? [00:48] anything xml-based it easier to translate than non-xml docs [00:48] i mean, the default p-docutils+sphinx appearance (http://docs.python.org/dev/) is really neat and i can see how we could easily adapt it and create a(n) (x)ubuntu theme [00:48] and really... anyone who wants to contribute to docs is going to have to learn *some* syntax [00:49] true, but as i have understood, we have had some difficulties in getting new documentation guys [00:49] so the lower the barrier the better [00:49] but... i have concerns about having both xubuntu docs and ubuntu installed [00:49] the gnome doc guy has told me some of how it might work, but i'm not convinced [00:50] is there any way to test it for example in karmic alphas/betas with some really simple docs? [00:50] I'd expect a good documentation viewer to treat all installed documentation trees equal. [00:50] http://philbull.googlepages.com/Screenshot-HowcanIsendafiletosomeone.png [00:51] http://philbull.googlepages.com/yelp_mallard.png [00:51] that's ok as well [00:52] The most crucial thing is integration of individual component docs and different documentation sources. [00:52] the yelp developer did say that he'd be willing to create a sort of 'yelp library' that could be used by a different browser [00:52] Syntxes can be exchanged. [00:52] and JPohlmann seemed to be ok with the dependencies of that [00:53] JPohlmann: can you explain what you mean about "integration of different component docs"? [00:53] I still think DITA is better for all of this, anyway [00:54] DITA can do conditional texts... saying, "out of all of these subjects, only show the user ones that are relevant to Xubuntu" [00:54] If it's easy to write a doc viewer on top of that library, that would be cool. Unless yelp has only few dependencies and is able to show docs from different sources, then we wouldn't need another viewer. [00:54] j1mc: Well, assume you have separate docs for two applications and install them both. [00:55] Belinda Lopez from Canonical is here, and she's interested in DITA, too, but more for her own learning / training needs [00:55] The viewer needs to show both and needs to provide some kind of entry point so that users are able to navigate to the docs of both apps. [00:56] the GNOME doc lead is here, but they are all hacking on GNOME docs right now, so I think it would be better to talk to him about these concerns at a later time. [00:56] he's really bright, though. after all, he built this whole xml language [00:57] hacks on yelp and docutils... [00:57] still, the language is fairly experimental, and is not feature-complete yet [00:58] *sigh* ;) [00:58] Really, that leaves me without a clue what we should go for. [00:58] right [00:58] sorry [00:59] i am typing thing out in IRC, but i think i need to step back and look at things a little more clearly [00:59] look at what we need, and what each approach provides [01:00] :) [01:00] we don't want to adopt mallard and then have it not meet our needs or create conflicts with gnome [01:00] Right. But sphinx doesn't provide any integration or detection-on-the-fly features. [01:01] that's true [01:01] That seems more and more important. [01:01] but mallard currently doesn't include entities, and those make xml-based doc writing much easier. [01:02] Detection-on-the-fly is something only a special doc viewer can do anyway. HTML can't do that ;) [01:02] without entities, you end up writing the same stuff a bunch of times, and there's too much oppty for error [01:02] j1mc, Does mallard plan to include that or are the developers of mallard against it for some reason? [01:02] cody-somerville: good question, but I'm not sure. [01:03] this is what i'd really like to see: http://www.flatironssolutions.com/_webapp_973617/Dynamic_Content_Delivery_Using_DITA [01:03] see the pdf [01:04] that's more complex, though. [01:05] this is a good example of the advantages of DITA:http://www.uxmatters.com/mt/archives/2009/05/architecting-user-assistance-topics-for-reuse-case-examples-in-dita.php [01:07] but the DITA syntax is only marginally less complex than docbook, and authoring for content reuse is a little more technical endeavor. [01:08] that being said, DITA scales really well. [01:08] you take a bit more time to do it right, but then you can do more with it [01:08] hmmm [01:08] I just see a bunch of casserole recipes [01:08] haha [01:09] scroll down to the section: Figure 4—Conditional result statement [01:09] and imagine using Xubuntu or Ubuntu instead of Yankee Version or Southerner Version [01:10] Or... imagine saying, Xfce 4.6 does it this way [01:10] but Xfce 4.8 does it that way [01:10] * cody-somerville nods. [01:10] So the user could select what version of Xfce they have, and then they get the docs that are specific to that version [01:11] I would like to demo this using the standalone installation guide that the team is working on, but I haven't talked about it with the group yet [01:12] the installation guide would be a good test bed, I think, because installation is the same across versions [01:12] but you could easily spit out versions for each Ubuntu, Kubuntu, or Xubuntu [01:13] and you could provide one set of docs for a basic install (entire disk) but different docs for a more complex install [01:13] all from the same source [01:13] Interesting [01:13] Could things get "congested"? [01:14] Yeah, a little. As I said, the authoring aspect is more involved [01:14] that why I'd like to just demo this using the installation guide [01:14] and maybe that's all we use it for [01:15] sorry I've gotten a little off-topic [01:17] What I'd like to do is just put together a sample document of reasonable complexity in both mallard, rST-sphinx, and DITA [01:17] and compare / contrast the approaches [01:18] there's other stuff that we've learned and talked about this weekend, though. [01:18] it's been really neat. [01:19] http://twitter.com/#search?q=%23woscon09 & http://identi.ca/search/notice?q=woscon09&search=Search [01:19] I'm still mostly concerned about how to integrate docs from different packages nicely and how to present them to the user. [01:20] After all we talked about I see that nothing is mature and ready to be used. [01:20] The documentation community seems to be very active. That's cool [01:21] Yeah, it's not just linux folks here, either. The Drupal doc lead and several other Drupal doc folk are here, too. [01:23] JPohlmann: if you want to be able to build doc structures on the fly, yelp (or a home-built app built on a yelp library) would be our only approach right now, (afaik) [01:23] BTW, I'm browsing the worst form of documentation you can imagine right now ... API docs for the jpeg library in form of a .doc file ... [01:23] haha :) [01:24] And that file doesn't even use headers and stuff. It's just plain text in a .doc. [01:24] j1mc: Mallard is experimental and that yelp library doesn't exist yet, right? [01:25] you are correct [01:25] well, i think mallard is experimental [01:25] i've seen it build docs in yelp [01:26] or... mallard-based docs presented in yelp [01:27] i do not know how trivial or non-trivial it would be to create the 'library' [01:28] Ok [01:28] I agree that so far, mallard sounds most interesting. [01:29] I'd be interested in knowing whether yelp would be able to show different doc trees (like for Xfce *and* Xubuntu, or GNOME *and* Ubuntu *and* individual apps) at the same time. [01:29] If yelp does that and if yelp doesn't have any GNOME-specific dependencies, we don't need yelp library. [01:30] If it doesn't, it could be interesting if it's possible to write an application that does this based on the yelp library. [01:31] ok. I'll present this stuff to shawn. [01:31] Cool, thanks === pace_t_zulu_ is now known as pace_t_zulu [17:57] I had some suggestions for the ubiquity slideshow. [17:57] and I joined https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc [17:57] and I just posted my first message [17:57] But it told me the message must first be approved [17:57] because I'm not a list member, and it's a members-only list. [17:58] Did I miss some step as I was registering for the list? [18:00] ubu-noob: before you posted your message, did you receive a message with a confirmation link to click on? [18:01] jgoguen: I clicked on the confirmation - but I'm not sure if I did it before or after I sent the message to the list :-( [18:02] ubu-noob: OK, well if you clicked it and confirmed that you want to subscribe, any message after that from the same email address you registered with shouldn't get held for moderation [18:03] ubu-noob: the note you got explaining that your message is being held should have a link you can go to and cancel the message. You can try re-sending your message, and if it goes through cancel the first one. [18:03] ubu-noob: If you're using Gmail, you won't see your posting though. Your clue that it went through will be that you don't receive a notice of it being held for moderation... [18:04] jgoguen: Got it. Thanks. I'm going to try re-sending it now [18:05] ubu-noob: No problem :) [18:09] jgoguen: It posted! :-) Now I'll cancel the first one that was sent for moderation. It feels good when things work outl [18:09] ubu-noob: Indeed it does :) [18:16] jgoguen: FYI, I am on Gmail, and I did get a "ubuntu-doc post acknowledgement" for my successful post [18:17] ubu-noob: But not your actual post, just an acknowledgement that it was posted? [18:18] ( Of course, I never knew the lists had posting acknowledgements either... :) ) [18:18] jgoguen: Your message entitled [18:18] more, Ubiquity Slideshow for Ubuntu [18:18] was successfully received by the ubuntu-doc mailing list. [18:18] List info page: https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc [18:18] Your preferences: [18:18] EOF [18:19] jgoguen: laptop is dying. Must be off soon [18:19] ubu-noob: Best plug it in :) Glad to see things started working for you! [18:19] jgoguen: it may not be the default settings. I looked through and checked what fit best for me. [18:20] jgoguen: Yes, A/C power is good :-) Thanks again. Bye for now [18:20] Bye ubu-noob [19:33] Shouldn't https://wiki.ubuntu.com/ContributeToUbuntu#Writing%20Documentation have a different url for bug reporting? [19:33] "You can also file bug reports at https://bugs.launchpad.net/ubuntu-doc/+filebug for inaccuracies in Ubuntu's read-only documentation."