20:03:43 <annegentle> #startmeeting
20:03:44 <openstack> Meeting started Mon Jul  9 20:03:43 2012 UTC.  The chair is annegentle. Information about MeetBot at http://wiki.debian.org/MeetBot.
20:03:45 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
20:04:19 <annegentle> Agenda at http://wiki.openstack.org/Meetings/DocTeamMeeting
20:04:24 <annegentle> #topic Action items from last meeting
20:04:33 <annegentle> annegentle to investigate Starter Guide repurposing - Done, let's discuss with a "Starter Guide future" topic in this meeting
20:04:44 <annegentle> writerDiane to send mockup to ijw - Done, Ian sent back feedback on the format and content.
20:04:56 <annegentle> Rock, first topic done.
20:05:54 <annegentle> #topic Translation processes
20:06:05 <annegentle> This morning Ying Chun sent an email updating us on the status of their prototype for translations.
20:06:11 <annegentle> #link https://gist.github.com/3037139
20:06:16 <annegentle> #info Process for doc translation is in prototype stage.
20:06:26 <annegentle> As Ying Chun notes, the prototype uses the openstack-manuals repository to store the .po files.
20:06:50 <annegentle> I had been toying with the idea to have a separate repo for each language to house their manuals in - could be translations or originals.
20:07:11 <annegentle> I think we can keep with the prototype but also look into separate repos.
20:07:18 <annegentle> One important step in the workflow that she is still working on is how to handle updates to the English documents.
20:07:53 <annegentle> Any questions? Since the document of the prototype just came through about 12-14 hours ago I don't expect much reaction yet.
20:08:03 <annegentle> I think I am talking to myself… :)
20:08:18 <jgriffith> :)
20:08:24 <annegentle> :)
20:08:35 <annegentle> ok, more are joining and talking to me PM and IM and ahhh!!! :)
20:09:22 <annegentle> More to come on translation processes, but that's a good update!
20:09:29 <annegentle> v
20:09:30 <annegentle> er
20:09:31 <annegentle> #topic Starter Guide future
20:09:41 * koolhead17 looks around
20:09:45 <annegentle> I've sent an email to the CSS open source solutions group manager to discuss the future of the OpenStack Beginner's Guide also known as the Starter Guide.
20:10:06 <annegentle> Now that we have an Ubuntu and RHEL/Fedora install guide and are starting a translation process, it would make more sense to bring the Starter Guide into our usual processes with a license that would enable more contributors.
20:10:44 <annegentle> #info Anne discussing the future work on the Starter Guide, proposing a merge and re-licensing to bring it into OpenStack docs.
20:10:59 <annegentle> No real conclusions yet, just discussion.
20:11:08 * annegentle waves at koolhead17
20:11:31 * koolhead17 is  mute
20:11:35 <annegentle> any questions?
20:11:53 <annegentle> I'm keeping the pace going :)
20:11:57 <annegentle> #topic Redirects on diablo docs and file/ID renaming
20:12:35 <annegentle> When you do a Google search for "openstack ip addresses" an old file comes up, one that was renamed with an essex rewrite. It has "Diablo" in the header and all.
20:12:52 <annegentle> It was me, I did the renaming of the ID, now I need to figure out the best way forward for about 111 orphaned HTML files.
20:13:07 <annegentle> Yep. 111. For the Compute Administration Manual alone. Sigh.
20:13:20 <annegentle> I think I need to do a redirect for each individual file, knowing what it should point to. I've logged a doc bug to capture this work and assigned myself.
20:13:26 <annegentle> #link https://bugs.launchpad.net/openstack-manuals/+bug/1022712
20:13:28 <uvirtbot> Launchpad bug 1022712 in openstack-manuals "About 111 orphaned HTML files still can come up in Google searches" [Undecided,New]
20:13:58 <annegentle> ah, welcome Daisy_ !
20:14:14 <annegentle> I covered the translation process in the first topic, sorry!
20:14:17 <Daisy_> Good evening !
20:14:29 <Daisy_> it's all right
20:14:58 <annegentle> You can see the immediate log at http://eavesdrop.openstack.org/irclogs/%23openstack-meeting/%23openstack-meeting.2012-07-09.log
20:15:08 <Daisy_> thanks.
20:15:13 <annegentle> So far, no feedback, but I wouldn't expect any yet.
20:15:15 <annegentle> :)
20:15:33 <annegentle> ok, next topic
20:15:34 <annegentle> #topic DocImpact flag
20:15:48 <annegentle> So, I tried this myself on a patch by adding DocImpact to the commit message, and didn't see a notification email come through.
20:16:25 <annegentle> I talked to clarkb on the CI Team about it, but haven't figured out what the problem is. I think that the solution is probably to get us onto a real mailing list like the new dev list.
20:16:46 <annegentle> The CI team can move our mailing list to the new mailing list server, does that sound good?
20:17:24 <annegentle> I don't think it's controversially really :)
20:17:31 <annegentle> moving on...
20:17:32 <annegentle> #topic Articles rather than books
20:18:00 <annegentle> How interested are we in an article-based solution to documentation?
20:18:20 <annegentle> We've discussed a support knowledge base for example, and at the design summit we talked about a need for an article site.
20:18:32 <Daisy_> what's the differences?
20:18:46 <Daisy_> article based or book based?
20:18:51 <annegentle> right.
20:18:58 <annegentle> The doc tools team is prototyping a solution for Rackspace that OpenStack could consider. I want to hear from the community about the interest in such a solution.
20:19:31 <annegentle> To me, the book model and architecture of the current site is about right, but a support site would need articles.
20:20:07 <Daisy_> how can I know more about the prototype?
20:20:38 <annegentle> It's in the very early stages, but it's basically a change to the maven plugin that creates a deployable .war file and a front-end .jsp.
20:21:06 <annegentle> I think it's not quite what we'd want for OpenStack, as it's another layer that we'd need to figure out how to community-ize.
20:21:46 <annegentle> I can describe more if needed. It definitely complicates translation because instead of creating "books" it uses metadata to group topics and content.
20:22:07 <Daisy_> correct.
20:22:32 <Daisy_> if we cannot find strong reason to move, I will suggest to keep current one.
20:22:45 <annegentle> Daisy_: sounds good
20:23:04 <annegentle> I'd also like to explore ways to publish Docbook content to an article-based site
20:23:19 <annegentle> not completely revise our current info architecture but enable more articles.
20:23:38 <Daisy_> that's a good point.
20:23:48 <annegentle> And last but not least, congratulations and welcome to Atul Jha (koolhead17), our newest doc-core member.
20:24:11 <Daisy_> congratulations, Atul Jha!
20:24:18 <annegentle> #topic Open discussion
20:24:49 <Daisy_> I submitted a bug in bugzilla, asking to upgrade maven doc plugin to the lastest version.
20:25:00 <annegentle> Daisy_: ah yes, I tried to explain the use of -SNAPSHOT.
20:25:41 <Daviey> .
20:25:59 <Daisy_> Anne, when do you think the translation process can be ready to publish to community?
20:26:56 <annegentle> Daisy_: Let's see… would it make sense to send your latest progress to the openstack list (what you sent to the doc-core list)?
20:27:18 <annegentle> Daisy_: I also would like to work with you on an outline for the Beijing summit
20:27:20 <Daisy_> all right.
20:27:27 <Daisy_> thanks !
20:27:57 <notmyname> annegentle: we've got two upcoming changes in swift that may need doc updates
20:28:04 <annegentle> Daisy_: also, what is your sense of how "bad" (chaotic) it would be to enable a separate repo per language?
20:28:17 <annegentle> notmyname: ok, for the 1.5.0 or 1.5.1?
20:28:56 <Daisy_> Anne: hard to syncronize between so many repositories
20:29:04 <notmyname> annegentle: one in 1.5.1 (scheduled to be released next week, but that may slip) and the other might be in 1.5.1 but may slip to 1.5.2
20:29:13 <annegentle> Daisy_: when I've talked to people about it, they usually see gains in having native-language authors reviewing updates, but I'm not sure how much new documentation we would see in non-English languages.
20:30:01 <notmyname> annegentle: the first (in 1.5.1) is the bin/swift separation to the python-swiftclient repo. python-swiftclient is now a dependency of swift
20:30:26 <annegentle> notmyname: I did an update of the python-swiftclient docs and noticed that there's no swift CLI documentation with it. Will there be?
20:30:47 <notmyname> I don't know. I've been out and I'm just now catching up on things
20:31:02 <annegentle> notmyname: https://review.openstack.org/#/c/9353/ is the review for my minor edits
20:31:18 <Daisy_> Anne: the native language authors can review throught Transifex UI. We separate the whole doc document into segement and use Transifex to translate, because we want to leverage crowed people to help translation.
20:31:20 <annegentle> notmyname: yeah you escaped the heat here! (So did I last week) :)
20:31:36 <notmyname> I had to wear a hat to go to the store last night!
20:32:15 <annegentle> Daisy_: ok, that's true. Really the Gerrit/Github workflow would be more for original authored documentation in a non-English language.
20:32:30 <notmyname> annegentle: eventually python-swiftclient should have its own docs, but for now if there was nothing in the main swift repo (I don't think there was), then there is nothing for python-swiftclient
20:32:32 <annegentle> Daisy_: perhaps I don't want to introduce so much chaos and need to be told so :)
20:32:53 <annegentle> notmyname: the only swift CLI docs are ones I wrote from a letterj blog post :)
20:33:02 <notmyname> annegentle: ok :-)
20:33:41 <koolhead17> annegentle, is someone already working on Cinder and Quantum doc?
20:33:43 <annegentle> #link http://docs.openstack.org/trunk/openstack-object-storage/admin/content/swift-cli-basics.html
20:33:59 <notmyname> annegentle: the second change is the keystone auth middleware that is moving into the swift repo (from the keystone repo). this change might land this week in time for 1.5.1, but if not it will be in the release after (probably called 1.5.2)
20:34:14 <annegentle> koolhead17: I have been talking to people about both, sometimes submitting patches even.
20:34:41 <annegentle> notmyname: yeah I wondered how best to handle that for docs. Not simple.
20:34:48 <koolhead17> annegentle, so can`t we involve some core devs for some help
20:34:59 <annegentle> koolhead17: absolutely.
20:35:26 <annegentle> koolhead17: so, Quantum has API and admin docs already. Cinder just started on dev docs last week I think.
20:35:38 <koolhead17> annegentle, ooh cool
20:36:02 <annegentle> koolhead17: what we will need to do for Folsum is figure out how to create "Compute | Storage | Networking" thinking about docs.
20:36:05 <koolhead17> at sametime we also need to keep distro packagers involved
20:36:09 <annegentle> I can't spell Folsom
20:36:17 <koolhead17> :P
20:36:34 <annegentle> notmyname: oh actually, moving the auth middleware into the swift repo is probably easier to explain.
20:37:37 <annegentle> #action Anne to send a memo to the mailing list about doc planning for Compute | Storage | Networking
20:38:14 <annegentle> Basically I want to get some clarity around what is Administration for OpenStack Compute - it involves block storage and networking now
20:38:24 <annegentle> (well, when "now" is trunk/folsom)
20:38:34 <annegentle> So I need to work on the info architecture for all documentation
20:40:21 <annegentle> notmyname: thanks for the doc requests. I'd like to track with a doc bug  or two - the lack of Swift CLI docs is noted here
20:40:25 <annegentle> https://bugs.launchpad.net/openstack-manuals/+bug/1019718
20:40:26 <uvirtbot> Launchpad bug 1019718 in openstack-manuals "Need docs for swift CLI comparable to nova CLI" [Medium,Confirmed]
20:41:39 <annegentle> notmyname: The move of the keystone auth middleware, not sure that affects docs. More affects packagers - though docs are still needed. I can log a doc bug to track that work.
20:42:03 <annegentle> Ok, anything else?
20:42:34 <koolhead17> annegentle, it will be good if we can get some help from the distro side
20:42:37 <koolhead17> as in packagers
20:42:52 <annegentle> We need more doc resources all the time :)
20:43:11 <annegentle> Ok, thanks everyone.
20:43:13 <annegentle> #endmeeting