20:03:43 #startmeeting 20:03:44 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 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 20:04:19 Agenda at http://wiki.openstack.org/Meetings/DocTeamMeeting 20:04:24 #topic Action items from last meeting 20:04:33 annegentle to investigate Starter Guide repurposing - Done, let's discuss with a "Starter Guide future" topic in this meeting 20:04:44 writerDiane to send mockup to ijw - Done, Ian sent back feedback on the format and content. 20:04:56 Rock, first topic done. 20:05:54 #topic Translation processes 20:06:05 This morning Ying Chun sent an email updating us on the status of their prototype for translations. 20:06:11 #link https://gist.github.com/3037139 20:06:16 #info Process for doc translation is in prototype stage. 20:06:26 As Ying Chun notes, the prototype uses the openstack-manuals repository to store the .po files. 20:06:50 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 I think we can keep with the prototype but also look into separate repos. 20:07:18 One important step in the workflow that she is still working on is how to handle updates to the English documents. 20:07:53 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 I think I am talking to myself… :) 20:08:18 :) 20:08:24 :) 20:08:35 ok, more are joining and talking to me PM and IM and ahhh!!! :) 20:09:22 More to come on translation processes, but that's a good update! 20:09:29 v 20:09:30 er 20:09:31 #topic Starter Guide future 20:09:41 * koolhead17 looks around 20:09:45 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 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 #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 No real conclusions yet, just discussion. 20:11:08 * annegentle waves at koolhead17 20:11:31 * koolhead17 is mute 20:11:35 any questions? 20:11:53 I'm keeping the pace going :) 20:11:57 #topic Redirects on diablo docs and file/ID renaming 20:12:35 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 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 Yep. 111. For the Compute Administration Manual alone. Sigh. 20:13:20 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 #link https://bugs.launchpad.net/openstack-manuals/+bug/1022712 20:13:28 Launchpad bug 1022712 in openstack-manuals "About 111 orphaned HTML files still can come up in Google searches" [Undecided,New] 20:13:58 ah, welcome Daisy_ ! 20:14:14 I covered the translation process in the first topic, sorry! 20:14:17 Good evening ! 20:14:29 it's all right 20:14:58 You can see the immediate log at http://eavesdrop.openstack.org/irclogs/%23openstack-meeting/%23openstack-meeting.2012-07-09.log 20:15:08 thanks. 20:15:13 So far, no feedback, but I wouldn't expect any yet. 20:15:15 :) 20:15:33 ok, next topic 20:15:34 #topic DocImpact flag 20:15:48 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 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 The CI team can move our mailing list to the new mailing list server, does that sound good? 20:17:24 I don't think it's controversially really :) 20:17:31 moving on... 20:17:32 #topic Articles rather than books 20:18:00 How interested are we in an article-based solution to documentation? 20:18:20 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 what's the differences? 20:18:46 article based or book based? 20:18:51 right. 20:18:58 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 To me, the book model and architecture of the current site is about right, but a support site would need articles. 20:20:07 how can I know more about the prototype? 20:20:38 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 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 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 correct. 20:22:32 if we cannot find strong reason to move, I will suggest to keep current one. 20:22:45 Daisy_: sounds good 20:23:04 I'd also like to explore ways to publish Docbook content to an article-based site 20:23:19 not completely revise our current info architecture but enable more articles. 20:23:38 that's a good point. 20:23:48 And last but not least, congratulations and welcome to Atul Jha (koolhead17), our newest doc-core member. 20:24:11 congratulations, Atul Jha! 20:24:18 #topic Open discussion 20:24:49 I submitted a bug in bugzilla, asking to upgrade maven doc plugin to the lastest version. 20:25:00 Daisy_: ah yes, I tried to explain the use of -SNAPSHOT. 20:25:41 . 20:25:59 Anne, when do you think the translation process can be ready to publish to community? 20:26:56 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 Daisy_: I also would like to work with you on an outline for the Beijing summit 20:27:20 all right. 20:27:27 thanks ! 20:27:57 annegentle: we've got two upcoming changes in swift that may need doc updates 20:28:04 Daisy_: also, what is your sense of how "bad" (chaotic) it would be to enable a separate repo per language? 20:28:17 notmyname: ok, for the 1.5.0 or 1.5.1? 20:28:56 Anne: hard to syncronize between so many repositories 20:29:04 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 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 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 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 I don't know. I've been out and I'm just now catching up on things 20:31:02 notmyname: https://review.openstack.org/#/c/9353/ is the review for my minor edits 20:31:18 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 notmyname: yeah you escaped the heat here! (So did I last week) :) 20:31:36 I had to wear a hat to go to the store last night! 20:32:15 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 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 Daisy_: perhaps I don't want to introduce so much chaos and need to be told so :) 20:32:53 notmyname: the only swift CLI docs are ones I wrote from a letterj blog post :) 20:33:02 annegentle: ok :-) 20:33:41 annegentle, is someone already working on Cinder and Quantum doc? 20:33:43 #link http://docs.openstack.org/trunk/openstack-object-storage/admin/content/swift-cli-basics.html 20:33:59 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 koolhead17: I have been talking to people about both, sometimes submitting patches even. 20:34:41 notmyname: yeah I wondered how best to handle that for docs. Not simple. 20:34:48 annegentle, so can`t we involve some core devs for some help 20:34:59 koolhead17: absolutely. 20:35:26 koolhead17: so, Quantum has API and admin docs already. Cinder just started on dev docs last week I think. 20:35:38 annegentle, ooh cool 20:36:02 koolhead17: what we will need to do for Folsum is figure out how to create "Compute | Storage | Networking" thinking about docs. 20:36:05 at sametime we also need to keep distro packagers involved 20:36:09 I can't spell Folsom 20:36:17 :P 20:36:34 notmyname: oh actually, moving the auth middleware into the swift repo is probably easier to explain. 20:37:37 #action Anne to send a memo to the mailing list about doc planning for Compute | Storage | Networking 20:38:14 Basically I want to get some clarity around what is Administration for OpenStack Compute - it involves block storage and networking now 20:38:24 (well, when "now" is trunk/folsom) 20:38:34 So I need to work on the info architecture for all documentation 20:40:21 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 https://bugs.launchpad.net/openstack-manuals/+bug/1019718 20:40:26 Launchpad bug 1019718 in openstack-manuals "Need docs for swift CLI comparable to nova CLI" [Medium,Confirmed] 20:41:39 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 Ok, anything else? 20:42:34 annegentle, it will be good if we can get some help from the distro side 20:42:37 as in packagers 20:42:52 We need more doc resources all the time :) 20:43:11 Ok, thanks everyone. 20:43:13 #endmeeting