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