Documentation/MeetingLogs/DocTeam03122013

annegentle: #startmeeting Doc Team [08:03am] ek6 joined the chat room. [08:03am] annegentle: #topic Action items from the last meeting [08:03am] Daisy joined the chat room. [08:03am] lbragstad left the chat room. (Quit: Leaving.) [08:03am] annegentle: Let's see, Feb I was supposed to explain the principle of the doc sprint and ask for feedback on the ether pad. Did I? [08:04am] annegentle: I guess? [08:04am] fifieldt_: sure [08:04am] annegentle: ok, check [08:04am] annegentle: Also ACTION: Daisy write up what the role of a lead translator would be? And what permissions they'd need where? [08:04am] fifieldt_: done [08:04am] annegentle: Daisy: you wrote that up and are getting input [08:04am] Daisy: yes [08:04am] annegentle: And then ACTION: all to provide feedback on Daisy's proposal for translation access control [08:05am] Daisy: I got feedback. [08:05am] Daisy: That's done. [08:05am] annegentle: Daisy: do you feel you have enough feedback to go to the large mailing list (openstack@ lists.launchpad.net)? [08:05am] annegentle: cool [08:05am] Daisy: I think so. [08:05am] annegentle: good [08:05am] annegentle: ok, next one ACTION: all to start using #openstack-docs [08:05am] annegentle: yup! [08:05am] annegentle: ACTION: AnneGentle to formalise #openstack-docs, including justification for separate channel and any other necessary work to register the channel [08:05am] EmilienM: hi [08:05am] annegentle: done, we have channel bots, anything else we want in there, just talk to #openstack-infra [08:06am] annegentle: ACTION: AnneGentle to email the community once the channel is setup [08:06am] annegentle: Did I do that? My brain is fuzzy since the book sprint. [08:06am] sgordon: not sure but for the minutes it is #openstack-doc (no s) [08:06am] Daisy: hehe. We all know that now. [08:06am] Daisy: So it's done. [08:06am] annegentle: sgordon: oh that's right, thanks [08:07am] annegentle: Daisy: agreed, call it done [08:07am] annegentle: ACTION: all to discuss grizzly priorities on the mailing list (and work on them!) [08:07am] fifieldt_: carried over [08:07am] annegentle: fifieldt_: sent a good note to the mailing list so this is done, thank you Tom [08:07am] Daisy: not done [08:07am] annegentle: oh [08:07am] annegentle: I was thinking of your bug triage note, but that was to the docs- list [08:07am] sirushti joined the chat room. [08:07am] rkukura joined the chat room. [08:08am] annegentle: fifieldt_: were you going to send this to the larger list? Might be a good time to do it [08:08am] fifieldt_: indeed [08:08am] fifieldt_: will do that ~tomorrow [08:08am] annegentle: Alright, we'll carry that one over [08:08am] aabes joined the chat room. [08:08am] aabes left the chat room. [08:09am] annegentle: #action: fifieldt_ send a note to discuss grizzly priorities on the OpenStack mailing list [08:09am] annegentle: and then last one, fifieldt_ to followup with AnneGentle about the meeting time, heh heh. [08:09am] annegentle: I think I'm okay now with daylight savings? [08:09am] Daisy: that's done. [08:09am] fifieldt_: anne is here [08:09am] fifieldt_: success [08:09am] writerDi_: ha! [08:09am] annegentle: hee [08:09am] annegentle: sun's up! [08:10am] annegentle: okay, next... [08:10am] annegentle: #topic Operations Guide migration for translations [08:10am] annegentle: writerDi_ is bringing the HTML from Booktype into Docbook, and is nearly done [08:10am] timello joined the chat room. [08:10am] writerDi_: should be checked into the repo today [08:10am] annegentle: I tried to make one last PDF yesterday but the tool isn't working, I need to email adam Hyde to get that working again [08:10am] writerDi_: just doing final clean-up this morning [08:11am] annegentle: writerDi_: thank you! It is looking good. Is it using 1.7.1 of the maven plugin in the pom? [08:11am] writerDi_: yes! [08:11am] fifieldt_: cool [08:11am] annegentle: cool, hopefully that'll help with image resizing and so on [08:11am] annegentle: no orphans or widows in the PDF either, yay. [08:11am] writerDi_: yes, that's not hard to do [08:11am] annegentle: Daisy: what needs to happen on your end to get translations started? [08:12am] Daisy: I need Docbook, I think. [08:12am] dscannell joined the chat room. [08:12am] annegentle: Daisy: yup, we can just email you when the repo has it [08:12am] Daisy: After I get Docbook, I can convert to POT and upload to Transifex. Then translation can be started. [08:12am] annegentle: Daisy: it'll be in the openstack-manuals repo, in an openstack-ops directory [08:12am] writerDi_: correct! [08:12am] Daisy: OK. Got it. [08:13am] annegentle: Daisy: do we want to do any announcement on that openstack-translation list possibly? [08:13am] Daisy: I remember openstack_ha is also not in Docbook format. [08:13am] writerDi_: does that need to be converted? [08:13am] annegentle: Daisy: oh yeah but it gets converted to Docbook by jenkins [08:13am] Daisy: I don't think we need annoucement. [08:13am] annegentle: Daisy: okay [08:14am] Daisy: We don't have translator mail list till now. [08:14am] annegentle: Daisy: anything written in asciidoc or markdown gets converted to Docbook by Jenkins [08:14am] Daisy: I don't know we have such tools. [08:14am] annegentle: Daisy: but that's a good point [08:15am] annegentle: Daisy: how can the translation toolchain slice the docbook if it's on a guest host on Jenkins [08:15am] Daisy: Yeah. [08:15am] ijw left the chat room. (Read error: Connection reset by peer) [08:15am] annegentle: Daisy: I'm sure the -infra tooling could take care of it [08:15am] ijw joined the chat room. [08:15am] annegentle: Daisy: how is automation going anyway? [08:16am] Daisy: I add slicing tool to master repository today. [08:16am] annegentle: Daisy: nice. [08:16am] annegentle: #info The slicing tool for translating from Docbook is in the master repository now [08:16am] Daisy: Next is to invoke it from Jekins. [08:16am] Daisy: Not now. The patch is under review. [08:17am] annegentle: Daisy: ah, sure, but it'll get in [08:17am] Daisy: I need to upload a new version, somebody give me feedback. I need to revise the message. [08:17am] Daisy: Yes. [08:17am] annegentle: #info The slicing tool for translations is under review [08:17am] Daisy: When it is get in, I need to invoke it using Jenkins. [08:17am] annegentle: Any questions on the Operations Guide or translation? [08:18am] Daisy: Not now [08:18am] annegentle: Daisy: yes, let's see what happens [08:18am] writerDi_: yes - am i supposed to use the new cover in the docbook version? or the standard openstack cover? [08:18am] annegentle: I am very excited we had people wanting to translate it [08:18am] annegentle: writerDi_: ah good question. We can use the standard cover [08:18am] writerDi_: okay, cool [08:19am] Daisy: https://github.com/openstack/openstack- manuals /tree/master/ doc /src/docbkx/openstack-ha [08:19am] annegentle: writerDi_: for print purposes, our tool only outputs 8.5x11 (to my knowledge) so to use the cover we'd need Crown Quarto (a specific size) [08:19am] Daisy: I think openstack_ha is not converted. [08:19am] Daisy: do we need to convert it? [08:19am] writerDi_: i can do it if you need it [08:19am] annegentle: #action annegentle to ask Doc Tool team about Crown Quarto PDF output [08:19am] EmilienM: I've already did translation one time, I can help btw [08:19am] EmilienM: s/did/done [08:20am] annegentle: Daisy: there should be a Jenkins job that does the conversion, want me to find it? [08:20am] Daisy: yes, please. [08:20am] EmilienM: with some tools, but It was not really clean. I have to investigate the best way [08:20am] annegentle: EmilienM: okay, good to know [08:20am] annegentle: EmilienM: ideally we'll get it working in our toolchain [08:21am] EmilienM: annegentle: sure [08:21am] EmilienM: jenkins, etc.. [08:22am] annegentle: #link https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/manuals.yaml [08:22am] annegentle: the job name is openstack-ha-guide [08:22am] annegentle: and the pre builder section does the conversion I believe [08:23am] Daisy: annegentle: I mean, converting txt file to DocBook in order to support translation. [08:23am] EmilienM: annegentle: why do we have differents formats in manuals ? I was surprised when I've contributed to HA doc the first time [08:23am] Daisy: Do I make sense? The ha is not in DocBook format, so that my slicing tool doesn't work for it. [08:23am] annegentle: Daisy: see line 429, that's when it happens [08:24am] annegentle: "it" being the conversion to docbook [08:24am] annegentle: so within the Jenkins host machine, that file exists [08:24am] annegentle: we can talk more about it after the meeting too [08:24am] annegentle: ok, moving on to... [08:24am] Daisy: I see. [08:24am] annegentle: #topic Grizzly priorities [08:24am] fifieldt_: #link https://launchpad.net/openstack-manuals/+milestone/grizzly [08:25am] fifieldt_: #link https://launchpad.net/openstack-api-site/+milestone/grizzly [08:25am] annegentle: fifieldt_: nice work Tom [08:25am] annegentle: man that's a lot of confirmed grizzly ones [08:25am] annegentle: we really need a call out to the mailing list, our small team can't do it all [08:25am] fifieldt_: indeed [08:26am] annegentle: shall I send it today? [08:26am] fifieldt_: please do [08:26am] annegentle: #action annegentle to send a call to action to help with grizzly doc bugs [08:27am] noslzzp joined the chat room. [08:27am] dprince joined the chat room. [08:27am] writerDi_: what's the deadline to get into grizzly? [08:27am] annegentle: fifieldt_: the priorities look good so I think people can follow them [08:27am] fifieldt_: good [08:27am] annegentle: writerDi_: what we do is keep an eye on that list and release when the docs are "mostly" complete [08:27am] annegentle: writerDi_: it is a judgement call, but usually a month after the release date. [08:28am] writerDi_: okay! i can take a few more - assigning myself a few bugs [08:28am] annegentle: writerDi_: Grizzly code release is April 4th [08:28am] annegentle: writerDi_: Great! [08:28am] Daisy: I can help too. [08:29am] annegentle: Daisy: thanks [08:29am] annegentle: #topic Using 1.7.1 version of Maven plugin [08:29am] annegentle: The Compute Admin manual is using 1.7.1 version of the Maven plugin successfully for weeks now [08:29am] fifieldt_: great [08:29am] annegentle: so I think we can migrate the rest over, but it does take a while since there are about 30 pom.xml files at last count [08:30am] annegentle: The doc tool team has offered to help out, since the pom.xml has to change to remove the <postProcess> section [08:30am] fifieldt_: cool [08:30am] annegentle: I'd rather prioritize bugs, seeing that grizzly list And ask for help from the doc tool team [08:30am] fifieldt_: sounds good [08:30am] annegentle: the awesome thing is, we don't have to change any CI jobs. WHEW. [08:31am] fifieldt_: yay [08:31am] annegentle: now I am trying to remember if I documented what has to change, I'm going to set an action item to document it [08:31am] annegentle: #action annegentle to add info about pom.xml change for 1.7.1 to wiki [08:31am] annegentle: #topic Docs-draft work for easier reviews [08:32am] dscannell left the chat room. (Quit: Leaving.) [08:32am] annegentle: Another cool update, ladquin is working on a patch in the -infra/config project to let the Jenkins jobs build a draft copy and put it on http://docs-draft.openstack.org for reviewers to see. [08:32am] fifieldt_: yayy [08:32am] writerDi_: that's great! we need that [08:32am] annegentle: great work ladquin [08:32am] Daisy: great ! [08:33am] annegentle: we'll revise the "review process" once that's in place, it lets reviewers see the HTML [08:33am] cp16net|away is now known as cp16net. [08:33am] ladquin: got a patch to update with more jobs, but.. [08:33am] EmilienM: very nice [08:33am] ladquin: about that.. it'd be useful to know beforehand if any output folder / final directory should change for any of the builds [08:33am] ladquin: will the pom modification change that too? [08:34am] annegentle: ladquin: ohhh we change the final directory all the time in the jobs, is that what you mean? Like /releasename/openstack-compute/admin? [08:34am] ladquin: yup [08:34am] annegentle: ladquin: yeah for 1.7.1 that's set in the pom.xml, for 1.5.2, it's also set in the pom.xml in the postProcess area [08:34am] ladquin: it's not a big deal to update the jobs, I just don't want to get anything broken over there [08:35am] annegentle: ladquin: yeah, ideally it'll mimic what's on docs.openstack.org [08:35am] ayoung joined the chat room. [08:35am] annegentle: ladquin: so at any given time you could see a "mirror" of docs.openstack.org on docs-draft.openstack.org [08:35am] ladquin: ok, but if we're migrating the other poms.. will they change too? [08:36am] annegentle: ladquin: the pom.xml itself changes but the folder names don't change does that make sense? [08:36am] lbragstad joined the chat room. [08:37am] • annegentle looks for an example [08:37am] ladquin: yeah.. I just can remember if David changed the final output folder [08:37am] fifieldt_: one to take offline? [08:37am] ladquin: s/can/can't [08:37am] annegentle: ladquin: yeah line 94 of https://github.com/openstack/openstack-manuals/blob/master/doc/src/docbkx/openstack-compute-admin/pom.xml [08:37am] annegentle: fifieldt_: yeah good point [08:38am] annegentle: ladquin: we'll figure it out after the meeting [08:38am] ladquin: ok, no problem! [08:38am] annegentle: #topic Navigation coming soon for api.openstack.org/api-ref.html [08:38am] fifieldt_: sounds good [08:39am] annegentle: just a note from the doc tool team, they should have a working solution for the long listing of API calls [08:39am] writerDi_: awesome! [08:39am] annegentle: now, ladquin and I are trying to figure out a solution for the nova api samples being held in another repo [08:39am] annegentle: which kind of affects navigation for that site, but we are still discussing with the -infra team and so on [08:40am] annegentle: it's not that we want to treat one API differently, but the nova api has the most samples and longest listing [08:40am] annegentle: so one idea is to make a patch to nova to build the api page from their repo [08:40am] annegentle: we're still formulating it, and not even sure if the nova team would want that [08:40am] fifieldt_: #link https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site [08:40am] annegentle: the nova team and Sean Dague do want accurate samples [08:40am] annegentle: fifieldt_: yep, that's what ladquin also has on her todo list [08:41am] annegentle: so, lots of cool solutions in the pipeline! Just want to get the right ones in place. [08:42am] annegentle: originally we were just going to copy files over, automate that, and so on, but fungi on the infra team wasn't so sure. or was it clarkb? [08:42am] ladquin: I wonder what's better / more efficient.. either patchig api-site now or migrating first and then patching [08:42am] ladquin: fungi was [08:42am] markmcclain joined the chat room. [08:43am] fungi: me [08:43am] annegentle: Anyway, their point was that you can't always automate a job change trigger, or at least, it's hacky. [08:43am] annegentle: hey fungi ! [08:43am] • fungi waves [08:43am] annegentle: I think they've given us good guidance, so we're noodling on the best way forward. [08:43am] ladquin: hey [08:44am] • fifieldt_ needs to zzz [08:44am] annegentle: So the new idea, to summarize, is to move wadl, xml, etc. to the nova repo [08:44am] annegentle: fifieldt_: no worries, you can catch the notes, open discussion is the last thing! [08:44am] fifieldt_: night [08:44am] fifieldt_ left the chat room. [08:45am] annegentle: writerDi_: the moving of the WADL to the nova repo may affect the spec (as in, the spec won't be able to easily get the WADL source-of-truth) but the compute spec doesn't really get updated much [08:45am] writerDi_: okay [08:46am] annegentle: writerDi_: but definitely something to think about, not even sure if the nova team would accept such a patch [08:46am] writerDi_: hmmm - the spec doesn't refer to the WADLs, right? just the api-site [08:46am] annegentle: writerDi_: right [08:46am] writerDi_: even though the spec SHOULD refer to the WADLs [08:46am] annegentle: writerDi_: or at least have some known source of truth [08:46am] annegentle: the spec does point to the latest samples tho [08:46am] annegentle: though [08:47am] pnavarro joined the chat room. [08:47am] writerDi_: this would be a good time to revamp the nova spec/api-site so that the spec is more guidance and the api-site is the reference [08:47am] annegentle: writerDi_: sure [08:47am] writerDi_: we can talk about it [08:47am] pnavarro left the chat room. (Client Quit) [08:47am] annegentle: writerDi_: my guess is that the nova guys will be split: they will want docs closer to their code, but they won't want a new tool (maven) in their builds [08:47am] annegentle: writerDi_: nova builds are biggggg [08:48am] writerDi_: okay [08:48am] annegentle: but, it's worth a discussion for sure [08:48am] annegentle: ok, moving along [08:48am] annegentle: #topic open discussion [08:48am] pnavarro joined the chat room. [08:48am] annegentle: I've been urged to invite ladquin to join docs-core! So I'll be sending an email about that after the meeting. [08:48am] annegentle: congrats Laura! [08:49am] ladquin: :") [08:49am] ladquin: thank you! [08:49am] writerDi_: CONGRATS! [08:50am] annegentle: as I told EmilienM, with great power comes great responsibility [08:50am] ladquin: I figure! [08:50am] EmilienM: sure [08:51am] annegentle: anything else or shall we take back 9 minutes from our day? [08:52am] annegentle: going... [08:52am] ladquin: nothing from here [08:52am] writerDi_ left the chat room. [08:52am] annegentle: going... [08:52am] mtreinish joined the chat room. [08:52am] annegentle: Okay, thanks all! Let's call it a wrap. [08:52am] annegentle: #endmeeting