=== Burgundavia [~corey@S01060010dcc226d1.du.shawcable.net] has joined #ubuntu-doc === jsgotangco [~jsg@202.57.71.235] has joined #ubuntu-doc [02:45] good morning [02:46] salut [02:46] Burgundavia, what is happening? [02:47] not much [02:47] even svn isn't active [02:47] :( [02:47] no [02:47] I need to email elmo my new key [02:48] and then I will get active [02:48] ok === jiyuu0 [~jiyuu0@219.95.34.148] has joined #ubuntu-doc === thegreedyturtle [~thegreedy@user-0c93oto.cable.mindspring.com] has joined #ubuntu-doc [04:17] thegreedyturtle, hi there === jiyuu0 [~jiyuu0@219.95.34.148] has joined #ubuntu-doc [05:36] hey jsgo, sorry i was idle [05:36] still kinda am ;) [05:37] no worries === blahrus [~blahrus@12-223-50-121.client.insightbb.com] has joined #ubuntu-doc === jdub [~jdub@home.waugh.id.au] has joined #ubuntu-doc [05:42] hey [05:42] ok [05:42] quick summary [05:42] we want a web way to editing our docs in svn, using docbook [05:42] froud has investigated apache lenya [05:42] seems like it meets our needs [05:43] we need a dev to look at it and give and upcheck/downcheck [05:43] a 'web way'? [05:43] editing online, ala a wiki, but into the svn repos [05:44] using docbook syntax? [05:44] yes [05:45] so writing docbook syntax into an html form that gets shunted into svn.. [05:45] yes, I believe so [05:45] that seems remarkably breakable and complicated for simple document editing procedures [05:45] I have not played with lenya myself [05:45] we are looking to involve a great many people in doc editing [05:45] provide a single source [05:45] and keep our existing infrastructure [05:46] that sounds like using an svn or baz repository directly to me - i don't understand the web page requirement [05:46] the web requirement is to lower the exisiting barrier to editing [05:46] think of this as rosetta vs a gnome-translator [05:47] it doesn't lower the barrier usefully [05:47] the writer still has to author docbook [05:47] can i make a comment [05:47] and they're stuck in an htmlarea instead of a text editor [05:47] jsgotangco, jump in [05:48] i still don't see the point of the portal since the manual author still has to dump his thoughts in an html text area [05:48] (i see lenya has some element of wysiwyg editing, but has an awful chunk of infrastructure underneath it) [05:48] ok [05:49] (the awful chunk of intfrastructure can be the xslt stuff) [05:49] the team almost ripped itself apart in January discussing major changes [05:49] we decided that the path of least resistance was to develop a web portal to our existing docbook/svn stuff [05:50] that sounds like a heck of a lot of wasted time to me [05:51] can you suggest a better solution (I am asking seriously) [05:51] sorry, but a good editor, sensible revision control (svn or preferably baz) and useful preview tools (yelp) are all you need to start writing and contributing good documentation [05:52] what about single source? [05:52] I want to remove all docs from the wiki (hopefully) [05:53] so, you have to get used to the idea that it will never happen :) [05:53] i still like our current setup [05:53] (its quite simple really) === Burgundavia is very very frustrated now [05:53] official documentation in revision control and in the distro (packages) is hugely beneficial === Burgundavia really really really should have been at UDU [05:54] because you have a clear place to contribute (both docs, translations, etc) [05:54] and a clear delivery path (packages in the distro) [05:54] you could also autogenerate them for a website [05:54] what about on the web? [05:55] if you want to deliver them to a website, that's really simple [05:55] there will always be stuff going on in the wiki [05:55] ok [05:55] I am talking single source [05:56] the wiki is currently filled with crap, from our perspective [05:56] in fact, having the wiki makes finding people for the documentation team so much easier [05:56] most of what we are discussing has been hashed out many times on the doc team lists [05:56] we can pluck great contributors from the wiki into the doc team, and get them working on the distro docs [05:56] I am trying to move forward what we discussed there [05:57] ok, so my suggestion for moving forward: [05:57] * docbook in revision control [05:57] but you are failing to address the major issue that still exists [05:57] * attempt to automate package building for testing purposes [05:57] * do some gonzo web delivery for testing purposes, maybe spruce it up and make it sexy later on [05:58] what about getting it back from the web? [05:58] * hack more talk less! :) [05:58] jdub, ROCK [05:58] I am trying to get something together here [05:58] jsgotangco, to be honest, you are not helping [05:58] I am very very mad now [05:58] well, further down the track we could look into doing documentation commentary like php.net, but in the distro instead of on the web [05:58] Burgundavia, i don't seewhy we have to complicate this to be honest [05:58] but there's no point making things complicated to start with [05:59] my problem at the moment is that no one is pulling docs from svn except some people [05:59] I am going to walk away, and when I come back, I am going to post a message to the devel list about what the doc team has dicussed, what we have found, and where we need to move [05:59] our svn is still empty [05:59] jsgotangco: empty? [05:59] i thought all the distro doc bits were in it [05:59] empty as in old docs [06:00] i meant it still has old docs [06:00] its not really moving that much [06:00] yeah [06:00] just look at the commit list [06:00] seems there's more discussion about infrastructure issues than actual doc hacking :) [06:00] i know [06:00] thats why i believe froud is getting frustrated at this [06:01] this is not a complicated issue [06:03] jdub, http://lists.ubuntu.com/archives/ubuntu-doc/2005-May/002220.html [06:04] ok [06:04] sorry, needed to blow off steam [06:04] Sean and I have spent the past 2 months talking about this issue [06:04] and this is what we came up with [06:04] so, yes there has already been a lot of talk [06:04] this is about how to move it forward [06:05] i don't see the necessity for a "web portal" to move forward [06:05] we already have the tools [06:05] basically, I said, we need a web way to edit stuff [06:05] but you don't [06:05] sean said, lets not lose the exisiting infrastructure [06:05] jdub, would it be possible to consider this for the future instead for this release cycle [06:06] you have a much better tool on your hard disk [06:06] jsgotangco, no [06:06] a web browser is a hideous place to write docbook [06:06] at least let us try and then fail [06:06] you actually have all the tools you need already [06:06] before you condemn us to fail beforehand [06:06] I find that very annoying [06:06] i'm not saying it will fail [06:06] i can only imagine our portal becoming like the wiki sorry but that's how i feel about this [06:07] i'm saying you have everything you need to write and publish documentation [06:07] jsgotangco, we can control access to a web portal much easier [06:07] jdub, I am saying we don't [06:07] you don't need a web portal to write docs [06:07] jdub, you don't need rosettta to translate either, by the same logic [06:07] that's absolutely true [06:08] but it makes it easier [06:08] this is about making it easier [06:08] Ubuntu is about making it easier [06:08] dude [06:08] emotional argument is not useful argument [06:08] I am just very frustrating [06:09] because we have a workable solution [06:09] froud has tested it [06:09] we just need a dev to implement it [06:09] no, dude [06:09] this is silliness [06:09] you already have all the tools you need [06:09] every other project out there has written documentation without a 'web portal' [06:09] most docs suck [06:09] and they don't involve the community [06:09] in exactly the same way that every other project out there has translations done in emacs [06:09] that is incorrect [06:10] suffice it to say that we need a better way. We really do. The web is a very easy tool to getting people involved [06:10] lets harness that [06:10] i'm sorry, but this is emotional claptrap [06:11] a) you don't need a better way, you need to actually write docs [06:11] jdub, that is rude [06:11] b) you don't need more people involved, you need a small team doing great work - *then* you can scale up [06:11] this is infrastructural fantasy stuff [06:14] the point about rosetta is fine, but translation has actually scaled to the point where rosetta can be useful [06:14] documentation, within ubuntu, has not [06:15] a better first step would be to have web based commentary on documentation, like php [06:15] then integrating that with yelp, the documentation reader in gnome [06:15] commentary on docs? [06:16] that will allow people to contribute to the documentation in a useful way, and have documentors operating as editors of those contributions [06:16] further down the track, using something similar to monodoc for user contributions far beyond commentary would be great [06:16] but it's very, very important to start small and scale up [06:16] then fundamentally is the difference between that and what I am proposing? [06:16] i'm talking about the future [06:16] nice things to have [06:16] I think the people will appear "when you build it" [06:17] they're entirely unnecessary for writing documentation right now, however [06:17] we have the best tools to hand already [06:17] revision control (svn or even better, baz) [06:17] we currently use svn, talk to us later about changing [06:18] we are also not going to change from docbook [06:18] emacs or vi with docbook/xml editing helpers, or even conglomerate if it's stable enough [06:18] thus, we need an easy way to involve people [06:18] conglomerate is not [06:18] ok, the easy way to involve people is this: [06:18] I use bluefish myself [06:18] do absolutely fantastic work and inspire people to get on board [06:19] look, docs are glamourous [06:19] every single barrier, no matter how small, that is in the way migth be the showstopper [06:19] observe gnome docs [06:19] i understand [06:19] ah, gnome documentation has different problems [06:19] related to scaling and branching [06:19] on the web eliminates a huge barrier of getting another program and learning how to use that, etc. [06:20] no, it doesn't significantly help [06:20] unless the user doesn't have to write docbook [06:20] I don't want documentors to have to deal with version control [06:20] taht should just happen [06:20] which can be done with desktop tools too :) [06:20] which ones? [06:20] eSVN? [06:20] no [06:20] dude [06:20] scale up [06:21] forget this infrastructure fancy [06:21] jdub, I am saying we will scale when we have the structure in place [06:21] the important thing is to do great work - that's what gets people interested to help out [06:21] you don't need to scale now [06:21] you need to start [06:22] please just implement the lenya thing, and then we can talk [06:22] we can make that an official request, if you want [06:22] "then we can talk"? [06:22] dude [06:22] seriously [06:22] Burgundavia, that didnt sound right === Burgundavia thought this would be easy [06:23] it's not easy because it's not right or compeling [06:23] compelling [06:23] the doc team doesn't need more infrastructure to write docs [06:23] it needs more docs :-) [06:24] that's what will get people interested [06:24] jsgotangco, have you read through the backlog of this channel and doc-list? [06:24] one of the past gnome doc team leaders learnt docbook specifically to contribute [06:24] i know guys who've learnt C to contribute to gnome [06:24] I am trying to find the email exchange mark, sean and I had [06:24] just a sec [06:25] Burgundavia, irclog no, but doc-list yes, for me its all pointless as no one is pulling docs from svn [06:25] svn is all that matters to me at the moment [06:25] the real lesson here is not to get bogged down in irrelevant details [06:26] start small, kick arse, scale when necessary, not before [06:27] i understand the attraction, but i've seen way too many projects kill themselves doing things that are unrelated to their real goals [06:27] i have to get some lunch :-) [06:28] me too [06:28] jdub, thanks for the time [06:28] jdub, take a read through this thread --> http://lists.ubuntu.com/archives/ubuntu-doc/2005-April/001755.html [06:58] so i just had a long walk to get lunch [06:58] and thought about a bunch of the problems [07:00] sounds good i just arrived from lunch as well [07:00] i think the first part is really basic [07:00] this talk about a web portal assumes that the major role of the doc team is 'writing docs' [07:01] where really, it isn't [07:01] at least not this early on [07:01] there's an enormous amount we can do simply by using what we have, and integrating it in a more useful way [07:01] there's very little that needs to be done from scratch [07:01] *very* little [07:04] that is the point of lenya [07:04] it is already a fairly mature app [07:05] oh, dude, come on [07:05] in fact, they just added some measure of WYSIWYG editing [07:05] ok i want to base on my experience im no docbook expert at all, sean took the time to mentor me and most of what I know came from him but it didnt stop me from doing stuff in what we currently have in a learning standpoint it is very interesting but can be intimidating to the new user [07:06] id rather have contributors who know some level of docbook or at least willing to bitethe bullet instead of giving them toned-down tools [07:06] too much abstraction muddles things [07:07] jdub, jsgotangco, sorry, my ex is calling, I must run [07:07] Burgundavia: "the point of lenya" is not to realise that we hardly need to write new docs at all [07:07] jdub, say again? [07:08] i've relayed a thought about hardly needing to write docs at all, and you've somehow related it to a document writing tool [07:08] it ends up sounding silly after a while [07:08] I am still not understanding what you are saying [07:08] hmm you mean using technology for the sake of technology instead of your end goal? [07:09] web based writing is not technology for the sake of technology [07:09] Burgundavia: you inserted your current argument into an unrelated point [07:09] ok [07:09] here's me saying we don't need to write new docs [07:10] and here's you saying "this is what a doc writing tool is for!" [07:10] it doesn't gel [07:10] and it sounds silly [07:10] ok [07:11] what I got from you is that current tools are suffecient not "we don't need to write new docs" [07:11] oddly, i'm saying both [07:12] what do you mean about writing new docs? [07:12] but the latter is a new thought [07:12] are you saying we just need to collate what is out there? [07:12] that is total crack [07:12] it is not total crack [07:12] we have a wealth of documentation already [07:12] it makes sense reusing what we currently have [07:12] and it is inadequately presented to users [07:12] good docs are visual [07:12] we just have to weed out the crack ones [07:12] visual requires screenshots/etc. [07:13] which are by there very nature Ubuntu specific [07:13] but you're assuming that requires fresh new documentation [07:13] at the very least, it requires major refactoring of exisiting docs [07:14] and ignoring the massive benefits we can give to users from existing works [07:14] no dude [07:14] even before refactoring [07:14] there is a lot we can do [07:14] for instance [07:14] sorry, really have to go this time [07:14] early in the warty cycle [07:14] my ex is here [07:14] countinue what you have to say [07:14] I can read in the scrollback [07:14] and respond later [07:14] i suggested (and thom implemented) integration of the debian doc metadata and OMF [07:15] suddenly, we almost doubled the documentation available in yelp [07:15] that's a huge win [07:15] with very little work [07:15] jdub, most argue that no one reads documentation in yelp [07:15] just pulling together stuff we already have [07:15] jsgotangco: well hey, lots of people argue that no one reads documentation :-) [07:16] ok same goes then so we have so much stuff in the wiki [07:16] some are gold, some are crack [07:16] i still believe we can weed out the crack in that [07:16] (i don't think either argument has much merit) [07:16] and integrate in current svn [07:17] yeah, there's a bunch of stuff we can do there [07:17] but there's way more we can do without even touching a line of docbook === thegreedyturtle [~thegreedy@user-0c93oto.cable.mindspring.com] has joined #ubuntu-doc [07:17] we all agreed in UDU that our wiki needs a facelift thats why we had a bof for that [07:18] yeah, switching away from zwiki will make life simpler [07:18] that was an unfortunate mistake [07:18] i still believe that since docbook gets frozen our wiki is the natural exgtension of the documentation therefore needs tighter controls [07:18] the wiki needs tighter controls? [07:19] well at least have someone review what people have been posting on it [07:19] 'hoy [07:19] yes [07:19] it needs farming [07:20] i kinda disagree with that, i think that the wiki needs to be very free, and then the docteam takes the best of it and moves it into the official docs [07:20] we shouldn't remove its collaborative nature [07:20] thegreedyturtle: (you're not disagreeing) [07:20] im disagreeing with the statement that the wiki needs tighter controls [07:20] thegreedyturtle: jsgotangco just clarified that [07:21] mm, im not so sure about even review myself though [07:21] it would be good for keeping the wiki organized though [07:21] every good wiki needs farmers [07:22] you end up with ambigious docs [07:22] clarify farmers? [07:22] farmers weed stuff [07:22] people who roam the wiki, tidying stuff up, culling the crap, etc. [07:22] got it [07:22] so far mdke is doing good work on that [07:24] is mdke post on the list at all? i don't have the names matched to the irc handles yet [07:24] im sure contributors are interested in learning some docbook [07:24] thegreedyturtle, mdke is matthew east [07:24] ok [07:24] jdub is jeff waugh [07:25] thanks [07:26] being fairly new myself, i think the biggest hurdle for new people isn't actually the docbook formats, but accessing the repositories [07:27] hmmm you mean by committing or just accessing [07:27] its not that difficult [07:27] a bit of both, and i know it's not difficult, but consider what happens when someone checks out the document source code [07:28] they suddenly get this huge dump of code, and it's easy to get overwhelmed [07:28] and then: what to do next? [07:28] well you check out svn because you expect that stuff right [07:29] well, you check out the svn because you expect it, and I check out the svn because I expect it, but someone who just wants to submit a quick document about how they made something work would not want that stuff [07:29] they just want to write a paper and feel good about it - which is why wikis are so popular... which brings us back to the root [07:30] we can't put all that stuff in svn much less include every contribution [07:31] very true - so the question here is how can we allow a user who doesn't want to deal with docbook and svn to contribute to something other than a wiki? [07:32] the simple way is to use farmers [07:32] thegreedyturtle: further down the track - annotated documentation, either on the web or in yelp [07:33] but it's *further down the track* [07:33] no point worrying about it now [07:33] righto [07:34] ok we're going back to where we started, this is not a complicated thing some people have submitted docs in OOo or other format and we've publishedit as docbook [07:34] so that's your earlier point about just getting something 'on paper' ? [07:35] you are saying that someone submitted as OOo and someone else did the conversion for them, right? [07:35] right [07:36] (although OOo to Docbook isn't the cleanest thing available at the moment) [07:36] from your experience, do you think that's scaleable? [07:36] another question, one of you mentioned that the svn documents are all old? [07:37] what are they old compared to? [07:37] another repo, the wiki, ... ? [07:37] (im kinda picking your brain now.. :) [07:39] if you mean scaleable in a sense that we can do it for everyone everyday, no its not the most effective way but we don't do that everyday [07:39] (i don't think traffic of that kind won't go up either) [07:40] when I said old, i meant hoary old docs since we're in breezy, there are some stuff that may not be applicable now [07:40] ok [07:40] (if you look at the commit list nothing much has moved either) [07:41] (which is understandable because we're still to early to do effective docs for breezy) [07:41] thegreedyturtle: luckily, we don't need to be concerned about scalability this early on :-) [07:41] right [07:41] you guys both running breezy right now? [07:41] my other machine runs breezy [07:42] is it worth running yet? [07:42] i wouldn't use it as main of course [07:43] ok [07:43] but some people i met in UDU run breezy in their laptops [07:43] mmm UDU, that was prolly lotsa fun neh? [07:44] it was fun but it was work at the same time [07:44] (we watched hitchiker's guide though) [07:44] brb [07:48] fun, work, what's the difference? [07:49] what do you usually use to edit docbook, just an xml editor? [07:50] heck even emacs will do [07:51] yeah but I'm lazy... [07:53] well being lazy won't start things really [07:54] it's not a lazy as in start things, more lazy as in i want the convenience of a simple editor, but i guess it doesn't matter [07:55] i like learning new stuff i guess it really depends on the person [07:55] i like learning stuff too, but right now im up to my nostril hairs [07:57] i have a subversion book to read, a docbook to read, and im still finishing essential sys admin, let alone my programming courses at college. I also want to at least get a small 'code portfolio' under my belt, and toss in a girlfriend... you get the idea :) [07:57] and I still needs a job... [07:58] hence, the easier it is to contribute, the more I'll be able to === jiyuu0 [~jiyuu0@219.95.34.148] has joined #ubuntu-doc [08:00] anyhoo, im off to work on the above list, i appreciate your ear [09:18] jsgotangco, check your mail [09:22] ok reading now === Liz [~Liz@fixed-203-87-27-63.nsw.chariot.net.au] has joined #ubuntu-doc [09:25] ok at least we'll know if we're go or no [09:25] basically I am tired of talking this issue [09:25] and jdub really really pissed me off [09:26] we have hashed out nearly every detail, we just need the implementation now [09:27] ill try out lenya myself later it looks mighty interesting [09:27] lenya looks really really cool [09:28] Morning [09:28] salut Kinnison [09:28] I was arguing with more people today [09:28] heh [09:28] this time it was jdub [09:28] I aim high === Kinnison grins [09:32] tomorrow it will be mark [09:32] oh wait, already done that [09:32] bugzilla bug 8516 [09:33] in other news, corey is looking forward to helping out more with malone [09:33] spatial? [09:33] yep [09:33] that was a nasty thread [09:33] Ubuntu spatial breaks usablity [09:33] Yeah, I don't like it, but my father does [09:33] the closing window way? [09:33]