Wednesday, 2017-06-21

*** masaki has joined #openstack-doc00:02
*** chlong has quit IRC00:03
*** yangyape_ has quit IRC00:17
*** yangyapeng has joined #openstack-doc00:20
*** amotoki_away is now known as amotoki00:23
*** yangyapeng has quit IRC00:25
*** yantarou has quit IRC00:56
*** yantarou has joined #openstack-doc00:57
*** yangyapeng has joined #openstack-doc01:21
*** yangyape_ has joined #openstack-doc01:25
*** yangyapeng has quit IRC01:28
*** KeithMnemonic1 has quit IRC01:39
*** lucasxu has joined #openstack-doc01:39
*** lucasxu has quit IRC01:39
*** dmacpher has joined #openstack-doc01:59
*** adisky_ has quit IRC02:03
*** zhugaoxiao has joined #openstack-doc02:13
*** thorst has joined #openstack-doc03:15
*** mikal_ is now known as mikal03:15
*** nicolasbock has joined #openstack-doc03:46
*** thorst has quit IRC03:54
*** yamamoto has joined #openstack-doc03:57
*** salv-orlando has joined #openstack-doc04:12
*** salv-orlando has quit IRC04:13
*** salv-orlando has joined #openstack-doc04:22
*** salv-orlando has quit IRC04:27
*** gouthamr has quit IRC04:43
*** salv-orlando has joined #openstack-doc05:02
*** emagana has joined #openstack-doc05:04
*** adreznec has quit IRC05:08
*** emagana has quit IRC05:17
*** salv-orlando has quit IRC05:39
*** salv-orlando has joined #openstack-doc05:39
*** salv-orlando has quit IRC05:44
openstackgerritMerged openstack/openstack-doc-tools master: Add openssl libs to bindep  https://review.openstack.org/47516205:58
*** andreas_s has joined #openstack-doc05:58
*** adreznec has joined #openstack-doc06:00
openstackgerritMerged openstack/openstack-doc-tools master: Updated from global requirements  https://review.openstack.org/47209506:04
*** pcaruana has joined #openstack-doc06:31
*** suyog has quit IRC06:45
*** rcernin has joined #openstack-doc06:59
*** edmondsw has joined #openstack-doc07:03
*** edmondsw has quit IRC07:08
*** tesseract has joined #openstack-doc07:15
*** emagana has joined #openstack-doc07:29
*** emagana has quit IRC07:33
*** jpena|off is now known as jpena07:37
openstackgerritRodolfo Alonso Hernandez proposed openstack/openstack-manuals master: Add "default" behaviour to QoS policies documentation  https://review.openstack.org/47448507:38
*** salv-orlando has joined #openstack-doc07:54
*** rcernin has quit IRC08:45
*** pnavarro has joined #openstack-doc08:47
*** rcernin has joined #openstack-doc08:50
*** edmondsw has joined #openstack-doc08:51
*** edmondsw has quit IRC08:56
*** dmacpher has quit IRC08:59
*** aspiers has joined #openstack-doc09:00
*** salv-orlando has quit IRC09:02
*** salv-orlando has joined #openstack-doc09:03
*** salv-orlando has quit IRC09:03
*** salv-orlando has joined #openstack-doc09:06
*** salv-orlando has quit IRC09:08
*** salv-orlando has joined #openstack-doc09:09
openstackgerritIsaac Beckman proposed openstack/openstack-manuals master: IBM Storage: add QoS documentation  https://review.openstack.org/47605609:11
*** dmacpher has joined #openstack-doc09:12
asettlesetuid: welcome to the ML09:12
*** yamamoto has quit IRC09:22
*** egallen has joined #openstack-doc09:26
openstackgerritMerged openstack/openstack-manuals master: split install guide into separate files by OS  https://review.openstack.org/47357909:43
openstackgerritMerged openstack/openstack-manuals master: remove the debconf version of the install guide  https://review.openstack.org/47547109:44
*** vijaykc4 has joined #openstack-doc09:46
*** yamamoto has joined #openstack-doc09:46
openstackgerritLuke Hinds proposed openstack/security-doc master: [WIP] Add Key Management Chapter  https://review.openstack.org/45196510:06
*** yamamoto_ has joined #openstack-doc10:09
*** charcol has joined #openstack-doc10:10
*** salv-orl_ has joined #openstack-doc10:12
*** yamamoto has quit IRC10:13
*** salv-orlando has quit IRC10:14
*** yangyape_ has quit IRC10:30
*** yamamoto_ has quit IRC10:30
*** yamamoto has joined #openstack-doc10:32
*** fragatina has joined #openstack-doc10:32
*** yamamoto has quit IRC10:33
*** fragatina has quit IRC10:34
*** fragatina has joined #openstack-doc10:34
*** edmondsw has joined #openstack-doc10:39
*** yamamoto has joined #openstack-doc10:43
*** edmondsw has quit IRC10:45
*** fragatina has quit IRC10:48
*** yangyapeng has joined #openstack-doc10:51
*** fragatina has joined #openstack-doc10:51
*** yamamoto has quit IRC10:54
*** ericyoung has joined #openstack-doc10:57
*** yangyapeng has quit IRC10:59
*** pnavarro has quit IRC11:01
*** andreas_s has quit IRC11:07
*** beekhof has joined #openstack-doc11:11
*** yamamoto has joined #openstack-doc11:24
*** yamamoto has quit IRC11:28
*** vijaykc4 has quit IRC11:31
*** yangyapeng has joined #openstack-doc11:36
*** yangyapeng has quit IRC11:41
*** yangyapeng has joined #openstack-doc11:41
*** dmacpher has quit IRC11:48
*** yamamoto has joined #openstack-doc11:54
*** charcol has quit IRC11:58
*** dmacpher has joined #openstack-doc12:02
*** fragatina has quit IRC12:04
*** jpena is now known as jpena|lunch12:07
*** masaki has quit IRC12:12
*** edmondsw has joined #openstack-doc12:21
*** dmacpher has quit IRC12:23
*** dmacpher has joined #openstack-doc12:35
*** vijaykc4 has joined #openstack-doc12:43
*** salv-orl_ has quit IRC12:54
*** salv-orlando has joined #openstack-doc12:56
*** salv-orlando has quit IRC12:57
*** salv-orlando has joined #openstack-doc12:58
*** jpena|lunch is now known as jpena13:01
*** gouthamr has joined #openstack-doc13:06
*** lucasxu has joined #openstack-doc13:07
*** salv-orlando has quit IRC13:08
*** salv-orlando has joined #openstack-doc13:12
*** dmacpher has quit IRC13:13
*** thorst has joined #openstack-doc13:16
setuidasettle: Thanks. I'm patching up the manuals so they build cleanly, against static versions (vs. pulled branches)13:17
setuidThat might help ease $CLIENT in the short term, while we talk about whether we can come up with a workable strategy and scrape up some resources who might be able to help13:18
*** thorst has quit IRC13:22
*** dmacpher has joined #openstack-doc13:25
*** eric_young has joined #openstack-doc13:31
sfinucanasettle, dhellmann: So I restructuring the nova docs last night and found that I really didn't like the 'cli' and 'config' sections... 🤷13:31
sfinucan*started restructuring13:31
sfinucanI also have mixed feeling on one or two of the other sections, and think we can definitely simplify things13:31
sfinucanAnywho - lots of comments left for y'all ;)13:31
*** thorst has joined #openstack-doc13:32
*** ericyoung has quit IRC13:33
*** pnavarro has joined #openstack-doc13:38
dhellmannsfinucan : hey, I just replied on the spec13:43
dhellmannlet me know if you want to chat here; I would like to resolve this so we can move ahead13:43
asettlesetuid: that sounds great :) tahnk you13:43
asettlesfinucan: grazie grazie13:43
asettleWill review13:43
*** catintheroof has joined #openstack-doc13:45
*** vijaykc4 has quit IRC13:47
*** vijaykc4 has joined #openstack-doc13:47
*** salv-orlando has quit IRC13:49
*** pnavarro has quit IRC13:49
asettlesfinucan: comment inline, hopefully that makes sense.13:56
sfinucanjinx13:57
sfinucanAh, so it's a matter of "let's just get this done asap". Makes sense (and why I didn't want to bikeshed) :)13:58
sfinucanI was thinking "well, we're already breaking all the URLs. Might as well shuffle things around"13:58
openstackgerritMerged openstack/openstack-manuals master: Build tr_TR arch-design  https://review.openstack.org/47535514:00
asettlesfinucan: yeah makes sense. I do genuinely agree with the points you make. I guess my major concerns is A: major disruption (but then as you say, why not do it all at once?!) is something I'd like to avoid. Plus, extra redirects14:00
*** pkovar has joined #openstack-doc14:01
sfinucanaye, and it's unlikely that we'd be able to get all projects on board like this again. Seemed like a "now or never" kind of opportunity14:03
asettlesfinucan: hmm I don't think it's a now or never, but then again, I'm very much thinking in the mindset that the 'docs team' would do this, as that's how we'd work.14:04
asettleThis now isn't the docs team taking charge, this is how the devs would read into it.14:04
asettleI guess I am concerned that so much disruption to our content will cause issues with our users and readers. But I don't want to bikeshed over this forever. We do have a sense of urgency here.14:04
sfinucanasettle: Yeah, I'm not sure how "we now need every project to spend time reshuffling thing around again" would pan out. My guess would be it wouldn't happen14:05
asettleYeah ^ that.14:05
*** pnavarro has joined #openstack-doc14:06
*** chlong has joined #openstack-doc14:07
sfinucanDoing it as part of the copy-paste process, on the other hand, would make two jobs into one ("all config-reference docs _except_ the autogenerated one now go into 'admin'. That one goes into 'reference'")14:09
sfinucanBut yeah, I get the urgency. I can disagree and commit, heh14:10
asettleHmmm let me think some more, and I'll get back to you if that's okay. I want to make sure we're going down the right path fully.14:11
sfinucanasettle: Sure thing :)14:12
sfinucanI'm in the same boat. We've one chance to do this right, so it's worth doing well, heh14:12
* sfinucan goes to draft things in nova and see how it works out14:12
sfinucan...while listening to James Blunts' (James Blunt!) kick-ass new album14:13
*** dmacpher has quit IRC14:20
*** dustins has joined #openstack-doc14:30
*** dmacpher has joined #openstack-doc14:33
*** gouthamr has quit IRC14:37
*** gouthamr has joined #openstack-doc14:38
*** emagana has joined #openstack-doc14:42
*** vijaykc4 has quit IRC14:48
ianychoiAJaeger, hello! Can I discuss some project-config structure regarding docs, checkbuild, and publishdocs jobs if you have time? Or if you share some documents then I would like to read it to grasp more details.14:50
*** vijaykc4 has joined #openstack-doc14:54
AJaegerianychoi: checkbuild is the draft pbulishing, publishdocs only publishes. See how we use them for openstack-manuals or security-guide14:55
AJaegerI meant: publishdocs publishes to docs.o.o14:55
AJaegerSo, checkbuild goes into check/gate queue, publishbuild only in post queue14:56
AJaegerNote that they invoke different tox targets14:56
ianychoiAJaeger, aha I see, then "docs" build intends for general documentation builds by calling a sphinx build script in project-config?14:58
ianychoiAJaeger, now I am a little bit confused with two things: One is https://review.openstack.org/#/c/471242/ - amotoki's suggestion is to support to use docs local tox.ini build script with publishdocs15:00
ianychoiAJaeger, and the other thing is https://review.openstack.org/#/c/475845/ - I previously assigned checkbuild just for checking pdf but it would be nice if openstackdocstheme makes use openstack-doc-tools to both have index.html to link html and pdf for checkbuilds and remove docs build?15:01
*** vijaykc4 has quit IRC15:02
AJaegerianychoi: in a call now, will try to check later.15:02
ianychoiAJaeger, I see thanks a lot :)15:02
*** vijaykc4 has joined #openstack-doc15:02
*** emagana has quit IRC15:03
amotokiianychoi: your understanding on my comment on using 'docs' target seems a bit incorrect. my point is just to avoid duplicate jobs since in your initial patch 'docs' and 'checkbuild' run exactly same things except copy the build to publish-docs dir. I did not see any value.15:03
amotokiianychoi: on the other hand, AJaeger's point is valid to me. we are trying to test different things in check/gate and post. we need to cover what 'post' does in check/gate queues.15:04
ianychoiamotoki, then what is the purpose in line 5487 on patch set 6: https://review.openstack.org/#/c/471242/6/jenkins/jobs/projects.yaml ?15:05
*** thorst has quit IRC15:05
ianychoiI thought that with it, docs environment in tox.ini will be executed instead of a script in project-config for docs job15:06
*** rcernin has quit IRC15:07
amotokiianychoi: your understanding is correct. It assume https://review.openstack.org/#/c/471220/13/tox.ini (i18n repo) is merged.15:07
amotokiianychoi: once it is merged, we will run the same build command in 'docs' and 'publishdocs' targets.15:07
ianychoiamotoki, and I have not seen the combination of docs + publishdocs - I previously saw just docs and [checkbuild+publishdocs].15:07
amotokiianychoi: i am okay with either name 'docs' or 'checkbuild', but they two are intended to do same thing in nature, so having both looks redundant to me.15:08
asettlesfinucan: sorry had meetings.15:09
ianychoiamotoki, I complete agree with you. I initially submitted to have three jobs: docs + checkbuild + publishdocs15:09
asettleHave you got a draft of how the nova stuff looks? I'd be interested in poking around15:09
ianychoiamotoki, now I am a little bit curious: when projects have just 'docs', or, ['checkbuild' + 'publishdocs'], or any other combination would be fine15:10
*** thorst has joined #openstack-doc15:12
amotokiianychoi: hmm... I don't want to stick the combination of job names only because it is adopted in openstack-manuals or manual-related projects.15:12
*** pnavarro has quit IRC15:12
amotokiianychoi: at least, 'checkbuild' only makes sense for docs project because other projects build other things as well.15:12
*** pcaruana has quit IRC15:12
amotokiianychoi: what does 'checkbuld' actually build in non-docs project?15:13
ianychoiamotoki, haha Me also don't want to stick :) Just my initial understanding was that checkbuild in manuals built translated guides and I thought having checkbuild would be a way to support to build translated guides15:14
amotokiianychoi: ah I see.15:15
ianychoiamotoki, but when I did further and further and translated guide support would be sufficient to have only publishdocs and my initial patch was somewhat messed15:16
*** thorst has quit IRC15:16
amotokiianychoi: yeah, that is almost same. one point to be improved is that publishdocs build script is run only in 'post' job. we should detect failures eariler if any. that's the point of my version.15:17
amotokis/almost same/almost true/15:18
-amotoki- is surprised why he used 'same' instead of 'true'....15:18
ianychoiamotoki, :) yep I got your point and agree with u!15:20
dhellmannasettle, sfinucan : I am less skeptical that we could get a "now let's reorg our docs" movement as a later phase, but if you want to do it in this one we just need someone to write down clear directions for deciding how to move what content to what directories.15:20
*** emagana has joined #openstack-doc15:20
asettledhellmann: do you think we could leave it? I mean, I would be interested mostly to see what sfinucan is doing and trial it in practice before we commit it15:21
dhellmannasettle : I'm not sure what you mean by "leave it"?15:23
asettleLeave the spec as is for now15:23
dhellmannoh, yeah15:23
dhellmannthat's what I'm saying: we could probably do some more work next cycle to merge the config guide and admin guide, if that's a thing we want to do15:24
dhellmannI thought we wanted them separate not because of where the content was managed but because sometimes people look specifically for how to configure and that's different from some of the other admin tasks15:24
dhellmannthe taxonomy for all of this content can go a lot of different directions15:24
*** emagana has quit IRC15:25
*** emagana has joined #openstack-doc15:27
dhellmannasettle, sfinucan : we left the release notes and api ref out of this phase, for example, so there's still going to be work to do15:29
*** sfinucan has left #openstack-doc15:30
*** sfinucan has joined #openstack-doc15:31
asettledhellmann: that's true15:31
asettleWe can have a 'phase two'15:31
dhellmannat least15:31
sfinucandhellmann: I'm not so concerned about release notes or api ref though, and moving those likely won't breaks links15:31
sfinucanWhat I'm trying to avoid is codifying what might be a slightly "off" way of doing things15:31
dhellmannwell, they will, since they will be published to completely different locations after the move15:31
dhellmannI'm trusting that the information architecture work that has already been done to decide to put config in its own guide is based on something other than conway's law. Maybe that's a bad assumption to be making.15:33
dhellmannI really don't know the right answer. Like I said, this could all go in lots of different directions.15:33
sfinucanGood point. I do consider those as separate things though :)15:35
sfinucanConway's law - that's exactly what I should have said. I do think it's a combo of people and tooling differences15:36
dhellmannI also wanted to avoid specifying anything below those top level directories, since even specifying *those* got some pushback. So if we're going to have a landing page to let people find all of the configuration information for a project, the link needs to point to a top level directory, not something under the admin directory. That's just my own rule, though, so maybe we want to amend that.15:36
*** thorst has joined #openstack-doc15:36
*** vijaykc4 has quit IRC15:37
sfinucanHmm, maybe we could encourage folks to only include the auto-generated stuff in 'cli'/'configuration'15:37
sfinucanand put the actual usage in usage section15:38
dhellmannwill readers make that distinction?15:39
asettleI think that'd be confusing15:39
asettleSorry I'm half in, half out15:40
*** thorst has quit IRC15:40
sfinucanIt's how we do it already, I think15:41
sfinucanI mean - here's the autogenerated stuff https://docs.openstack.org/newton/config-reference/compute/config-options.html15:41
sfinucanand then there's the rest of the guide15:41
sfinucanDocs like this [1], for example, are really usage docs in disguise [1] https://docs.openstack.org/newton/config-reference/compute/cells.html15:42
dhellmannsfinucan : some projects have a mix of hand-written content in the config guide: https://docs.openstack.org/ocata/config-reference/shared-file-systems/drivers.html15:43
dhellmannI really saw /user as end-user or consumer-of-cloud and not admin or deployer.15:44
dhellmannI agree the cells stuff could go in either /admin or /configuration15:44
sfinucani.e. "How does one setup cells". If I want to do anything with nova itself, it's likely I'd need to configure stuff. However, the configuration steps are merely artifacts of doing said thing15:45
dhellmannmaybe you're right, and /configuration should just be the auto-generated stuff15:45
sfinucanYeah, maybe I just have too much of a nova hat on15:45
dhellmannfrom what I can tell, coverage in projects varies pretty widely15:45
sfinucanIt should be much easier soon though15:45
sfinucanthey can all use oslo.config's Sphinx extension15:45
dhellmannsure, for the reference stuff15:46
dhellmannthere's still a need to write step-by-step guides like that cells page15:46
sfinucantrue15:46
dhellmannI'm ok with saying we put that in /admin15:46
sfinucanbut would any of those step-by-step guides fall under anything but "how do I administer my cloud"?15:46
sfinucangotcha15:47
dhellmannlet me rephrase: I'm ok with saying the /configuration section is only for auto-generated reference15:47
dhellmannthe install and admin sections should have the step-by-step stuff15:47
dhellmannwe can clarify that15:47
sfinucanyup, that would be a-ok by me15:47
sfinucana big improvement, in fact15:48
dhellmannthe reason for separating cli from user and reference is that there's a separate landing page that lists the command line reference guides15:48
* sfinucan is really looking forward to being able to cross-reference config options in the admin guides15:48
dhellmannso merging cli with user, while it makes sense, would make that page harder15:49
* asettle thinks sfinucan looks forward to strange things15:49
sfinucan:)15:49
asettle:p15:49
asettleSorry, I'm catching up and reading back15:49
sfinucandhellmann: Yeah, I'm also fine with keeping /cli15:49
sfinucanthough again, I'd argue autogenerated stuff only (basically man pages)15:49
dhellmannthat makes sense15:50
sfinucanThe actual use of those applications would be incidental15:50
dhellmannthat at least gives us clear directions for telling people how to move things around15:50
sfinucanYou just happen need to use them to administer a cloud15:50
sfinucanSweet15:50
sfinucanlast one - user15:50
* sfinucan reads back up for your comments on that one15:51
dhellmannnova needs an admin guide and a guide explaining to someone who is not an admin how to use nova15:51
dhellmannwhere does that go?15:51
asettle*raises hand* in what scenario is someone trying to use nova that isn't an admin? (Genuinely, I don't know)15:52
sfinucanhow would someone that isn't an admin use a cloud?15:52
sfinucanjinx :)15:52
dhellmannasettle : any API user15:52
asettleSnap15:52
dhellmannno, like LITERALLY 95% of our users are not admins15:52
asettledhellmann: but that doesn't differentiate what is 'administration' on a product.15:52
sfinucansorry - I mean use a cloud in any way except the API15:52
dhellmannwhat content is in the admin guide today? it's how to do things that a deployer can do but that a normal user cannot do, right?15:52
asettleYou can be a administrator of a product, and you can perform administration.15:53
asettledhellmann: actually I'd say those lines are a bit blurry15:53
asettleBased on my above statement15:53
dhellmannhow do you decide whether something goes in the admin guide or the ops guide today?15:53
asettleThe nature of the 'administration' guide was varied.15:53
asettledhellmann: based off practical or theoretical application, mostly15:53
asettleAlthough, the debate of the closeness of the two guides is never ending15:53
dhellmannthis section talks about config files: https://docs.openstack.org/admin-guide/identity-certificates-for-pki.html15:53
asettleThat's why we had that session at the summit15:53
dhellmannthat's not something an API user can deal with15:54
asettleAnd decided to get rid of the ops guide into a wiki15:54
dhellmannwe have a problem with the term "admin"15:54
asettleNo kidding15:54
dhellmannbecause to some people it's a verb and to some people it's a noun15:54
dhellmannand even then the scope varies15:54
asettleIn fairness, I wasn't around when that scope was defined, so I could be massively assuming. But that's how it looks to me.15:54
*** salv-orlando has joined #openstack-doc15:55
dhellmannI envisioned that section containing info you need to run the software, not use it.15:55
asettleI don't think, in this context, that there's anything wrong with a varied scope. Provided it targets a similar minded audience.15:55
asettledhellmann: it's... both? Because then we even have the End User Guide15:55
asettleWhich uh, also does both, more or less.15:55
dhellmannand I called it "admin" because that's where I said the stuff from https://docs.openstack.org/admin-guide/ should move15:55
asettleMOre user than running it, but yeah15:55
sfinucanI was guessing admin would contain anything that you needed to be in a datacenter to do15:55
asettleWhich would made sense.15:56
dhellmannsfinucan : in spirit, if not in body, sure15:56
sfinucanand I figured the API and client docs would contain references to how I, end-user X, would talk to any given cloud15:56
*** salv-orlando has quit IRC15:56
sfinucanHowever, thinking on it more, the API is a very rough tool15:56
dhellmannright. there's a lot of concept information that is not evident just from the api reference15:56
sfinucanand we'd probably still want some kind of guide that put things altogether15:57
sfinucanlike "how do I boot a VM with a PCI device"15:57
*** salv-orlando has joined #openstack-doc15:57
sfinucanyeah, hadn't thought of that15:57
dhellmannright, tutorials like that need a home15:57
sfinucanagreed15:57
dhellmannok, so let me try to summarize15:57
dhellmannwell, do we like contributor still?15:57
dhellmannor should that be internals?15:58
asettleI like contributor, mostly because it's consistent across the board. We talk about 'onboarding new contributors' not 'onboarding new internals'15:58
asettleThe language there is important.15:58
dhellmannwell, it would be "internals of this thing"15:58
asettleI don't think that improves clarity.15:58
dhellmannok15:59
dhellmannso keep that as is15:59
asettle*slams gavel*15:59
dhellmannconfiguration changes to only include the auto-generated content, with any long-form content such as the cells thing in the admin or install guide (whichever makes sense for each page)15:59
dhellmannright?15:59
asettleYep, I can agree with that one.15:59
dhellmannsfinucan has gone quiet15:59
asettleYou scared him dhellmann :P16:00
sfinucansorry - in three conversations at once :)16:00
* dhellmann is as gentle as a kitten with tiny knife-like claws16:00
sfinucanFine with all the above so far16:00
dhellmannwoot16:00
asettledhellmann: yeah precisely :P16:00
dhellmannok, cli is similarly restricted to auto-generated reference docs with tutorials and whatnot going into the user section16:00
dhellmannyes?16:00
asettleYep, also agree16:01
dhellmannthen we clarify admin to mean stuff answering the question "how do you run this software?"16:01
sfinucanyup16:01
asettleYeah, fair enough16:01
sfinucanyup16:01
openstackgerritMerged openstack/openstackdocstheme master: Update Site Search  https://review.openstack.org/47584516:01
dhellmannthe user section stays for end user content, like tutorials. we expect it to link heavily to the cli section or api section, depending on whether the repo is a service or a client16:02
asettleYep16:02
dhellmannwhat did we say about the reference section, is that name ok?16:02
*** tesseract has quit IRC16:03
asettleUhhh I think we agreed to keep it.16:03
dhellmannk16:03
dhellmannlet me spin a new patch quickly16:03
sfinucanone last one, would s/usage/howto/ make more sense?16:04
asettleVeto 'usage' but I Could go with 'how to' that's pretty common terminology16:04
asettleBut could be confused with things like 'tutorials 'etc16:04
sfinucansorry - I meant s/users/howto/16:05
dhellmannthere is no usage16:05
dhellmannok16:05
asettleAh16:05
dhellmannusers16:05
dhellmannhmm16:05
sfinucanit makes that section more specific16:05
sfinucanand stops it becoming a dumping ground16:05
dhellmannI guess we have a mix of "audience" and "content type" names16:05
dhellmannmaybe we should be consistent about that16:05
sfinucanah yes, don't want admins making a bee-line for usage16:06
sfinucan*howtos16:06
sfinucandammit16:06
sfinucanOK, cool cool. Once the intent of the directory is clear in the spec I guess we're good16:06
asettleOKay.16:07
dhellmannso keeping user is ok?16:07
sfinucanyup, fine by me16:07
asettleI'm in favour provided, as sfinucan says, that the intent is clear16:07
*** yamamoto_ has joined #openstack-doc16:10
dhellmannasettle , sfinucan : can we wordsmith on https://etherpad.openstack.org/p/SmdLiZJl5t instead of a bunch of little revs of the spec?16:11
sfinucan(y)16:11
asettledhellmann: can do. I'm about to scoot home to catch the train, but I"ll be able to review once I'm back16:11
asettleThat okay?16:11
dhellmannasettle : sure16:11
asettleGrazie grazie16:12
asettleOkay16:12
asettleo/16:12
*** salv-orl_ has joined #openstack-doc16:12
*** yamamoto has quit IRC16:13
*** thorst has joined #openstack-doc16:14
*** salv-orlando has quit IRC16:15
*** thorst has quit IRC16:19
sfinucandhellmann: Would a "how do I boot a VM with PCI device" go into nova or python-novaclient?16:19
dhellmannsfinucan : do you want to do it from the command line or from the api directly?16:19
sfinucanlets say both16:20
dhellmannif you're talking directly to the API, that would go in the nova docs. If you're using the command line that would either go in python-novaclient or python-openstackclient16:20
sfinucanactually, weren't we going to get rid of the direct API call docs?16:20
dhellmann"how do I use the tool in this repository to do X"16:20
dhellmannwere we?16:20
sfinucanAll the curl stuff, anyway16:21
dhellmannI don't know what's in the api-guides right now, because we said we'd move those later16:21
sfinucanUnless you mean using the client libraries in a scripting fashion16:21
dhellmannno, I meant curl16:21
dhellmannor whatever16:21
sfinucanyeah, I think that was mentioned at the summit16:21
dhellmannhand wavy instructions like "POST this JSON document to $url"16:21
*** egallen has quit IRC16:22
dhellmannhttps://developer.openstack.org/api-guide/compute/ will move to openstack/nova somewhere16:22
dhellmannI guess that's probably where it already is, isn't it16:22
sfinucanIt is, yes16:23
dhellmannso that's probably nova's user/ stuff16:23
sfinucanI'm guessing a lot of it is, tbh16:23
sfinucanIt's very hard to restrict yourself to one service for anything non-trivial16:24
dhellmannyeah, I mean, when it moves into the unified build it would go under user/ and stay in nova16:24
dhellmannyeah16:24
sfinucanbooting a VM with an SR-IOV NIC needs at least nova and neutron, and likely others beside16:24
sfinucanso it probably doesn't make sense in python-novaclient16:25
dhellmannthere's still room in the world for a "how to do something useful with openstack" guide, we just don't have a maintainer for it16:25
sfinucanTrue. Had the same issue with OVS, fwiw16:25
dhellmannthat specific example could live in either nova or neutron, with a reference from the guide for the other project to help with finding16:25
dhellmannmaybe that's the solution? the author picks, and we add hyperlinks16:26
*** egallen has joined #openstack-doc16:26
dhellmannI would guess a bunch of the stuff in the nova guide would include steps to talk to glance, cinder, etc. so I don't think that's a big deal.16:26
sfinucanI would suggest keeping 'user' in python-*client to the bare minimum "how do I execute/get help for this" docs16:27
sfinucanYeah, nova will likely inherit a lot of the guides. Lucky us, heh16:27
*** thorst has joined #openstack-doc16:27
*** thorst has quit IRC16:27
sfinucannova and neutron (the networking guide is not small)16:27
dhellmannthe networking guide is staying in openstack-manuals for now16:27
dhellmannoh, the spec still says it moves to neutron16:28
dhellmannasettle, what did we decide about the networking guide again?16:28
dhellmannI thought we changed our minds on that. We'll sort that out.16:28
sfinucanI brought all that up because I guess usage will be rather small for the clients16:29
dhellmannsfinucan : are you happy with the current text for these directories?16:29
sfinucanone last one16:29
dhellmannit might. it might also include docs for how to use the client libraries, not the cli16:29
dhellmannsfinucan : the user guide for clients needs to explain how to translate the API calls to CLI statements16:31
dhellmannso there may be a bunch of examples there, too16:31
dhellmannfor example, I don't think we want a tutorial that shows how to use the openstack command line tool to do something to nova in nova's repo.16:32
dhellmannwe would want a tutorial in nova's repo to use the API directly.16:32
sfinucanYou sure?16:32
sfinucanI'd imagine most users are using the clients16:32
dhellmannthat way as the API changes, the nova devs can update those docs and as OSC changes its devs can change its docs16:33
dhellmannI would too. We will certainly cross-link them.16:33
dhellmannbut not all users are, and not all API users are using python.16:33
dhellmannwe have a growing number of users talking to openstack from other languages16:33
sfinucanvery true16:34
dhellmannthe authors of gophercloud need docs, for example, and don't want to have to dig through cli code to translate examples that use the cli into API calls16:34
*** thorst has joined #openstack-doc16:34
dhellmannI keep coming back to describing this as "put the docs in the repo with the thing they are documenting"16:34
sfinucanYup, but the line between what thing you're talking about is blurry16:35
sfinucanboot w/ SR-IOV for example16:35
dhellmannyeah16:35
sfinucanWe don't want 'boot a VM w/ SR-IOV' in nova, and 'boot a VM' in novaclient16:36
dhellmannI don't know, maybe we shouldn't be too specific about that and let people figure it out for themselves16:36
sfinucanYeah, let's do that16:36
dhellmannI don't want to discourage someone from writing a bunch of how-to guides for the client libraries16:36
dhellmannshall I put this into the doc now?16:37
sfinucanI'm not looking forward to translating the likes of [1] to use REST calls instead of client calls though, heh [1] https://docs.openstack.org/admin-guide/compute-pci-passthrough.html16:38
sfinucandhellmann: Sure, go for it16:38
dhellmannok. I'll post this, and watch for asettle to review it when she's done with her commute16:39
dhellmannsfinucan : yeah, maybe that distinction I was trying to draw goes too far16:39
*** thorst has quit IRC16:39
openstackgerritDoug Hellmann proposed openstack/docs-specs master: Adds spec for migrating the documentation suite to project repos  https://review.openstack.org/47227516:40
sfinucanIt's a tough line to draw16:41
sfinucanbut we've got to start somewhere :)16:41
sfinucandhellmann: I'll review that first thing in the morning, but I'm guessing it's all good now16:41
sfinucanThanks for working through it :)16:42
* sfinucan packs bags16:42
dhellmannsfinucan : great, thanks for working through the details, I know it's late in the day for you16:42
sfinucanditto. Happy to help16:42
*** rbowen has joined #openstack-doc16:45
*** thorst has joined #openstack-doc16:47
*** yamamoto_ has quit IRC16:47
*** rbowen has left #openstack-doc16:47
*** yamamoto has joined #openstack-doc16:49
*** thorst has quit IRC16:51
*** egallen has quit IRC16:52
*** vijaykc4 has joined #openstack-doc16:57
*** thorst has joined #openstack-doc17:19
*** thorst has quit IRC17:24
*** emagana has quit IRC17:27
*** thorst has joined #openstack-doc17:28
asettlesfinucan and dhellmann - will look through a bit later17:32
asettleJust got home17:32
*** thorst has quit IRC17:34
*** thorst has joined #openstack-doc17:38
*** thorst has quit IRC17:40
*** emagana has joined #openstack-doc17:40
dhellmannasettle : slacker17:42
*** yamamoto has quit IRC17:42
asettleI know, I know17:42
*** pnavarro has joined #openstack-doc17:47
*** jpena is now known as jpena|off17:48
*** yamamoto has joined #openstack-doc17:51
*** vijaykc4 has quit IRC17:51
*** oanson has quit IRC17:52
*** oanson has joined #openstack-doc17:52
*** thorst has joined #openstack-doc17:53
*** vijaykc4 has joined #openstack-doc17:53
*** yamamoto has quit IRC17:56
*** thorst has quit IRC17:57
*** thorst has joined #openstack-doc18:00
*** vijaykc4 has quit IRC18:01
*** vijaykc4 has joined #openstack-doc18:03
*** thorst has quit IRC18:05
*** dustins_ has joined #openstack-doc18:07
*** dustins has quit IRC18:08
*** yamamoto has joined #openstack-doc18:15
*** vijaykc4 has quit IRC18:16
*** salv-orl_ has quit IRC18:17
*** vijaykc4 has joined #openstack-doc18:23
*** pkovar has quit IRC18:27
*** yamamoto has quit IRC18:44
*** emagana has quit IRC19:02
*** emagana has joined #openstack-doc19:02
asettledhellmann: sitemap is generated by running scrapy19:03
asettleAnd that's a bloody pita19:03
dhellmannI can imagine19:04
asettleAlso, comments inline on the etherpad19:06
asettleYes, it's not fun. But that's how we do it. Usually our release liaisons handle that19:06
*** emagana has quit IRC19:07
*** nicolasbock has quit IRC19:07
*** emagana has joined #openstack-doc19:17
*** thorst has joined #openstack-doc19:19
*** pnavarro has quit IRC19:24
*** pnavarro has joined #openstack-doc19:25
*** thorst has quit IRC19:27
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: add a global project list file for main site templates  https://review.openstack.org/47624719:34
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: templatize the language-bindings page  https://review.openstack.org/47624819:34
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: templatize more of openstack-projects list  https://review.openstack.org/47624919:34
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: stop generating content if a template can't be parsed or rendered  https://review.openstack.org/47625019:34
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: add jsonschema validation to the start of the template rendering  https://review.openstack.org/47625119:34
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: move library data from openstack-projects.html to projects.yaml  https://review.openstack.org/47625219:34
dhellmannasettle : what do you think about using a periodic job to just build that file on the site?19:37
*** fragatina has joined #openstack-doc19:39
asettledhellmann: no qualms19:39
dhellmannasettle : I don't want to keep you online late. The question on line 6 confused me though19:40
asettledhellmann: no problem, I'm online anyway :) let me check19:40
AJaegerdhellmann: do you want to merge the changes above now? I do not see a reason to have them stacked together on top of the others19:41
asettleAh, well, your explanation makes more sense. But then it definitely needs to be reworded. I read your explanation on lines 5/6 as something completely different.19:41
*** dmacpher has quit IRC19:41
asettle“however not all contributors are developers and "developer" can be interpreted as "contributor" and "user of this library””19:41
dhellmannAJaeger : at this point I've sort of lost track of what depends on what else, so I figured I'd just keep making that chain longer19:41
asettleDoesn't really say to me "we are changing from dev to contrib for these reasons"19:41
dhellmannoh, and these do depend on the earlier patch to move some of those templates around19:41
AJaegerdhellmann: if you're happy with the chain, fine ;)19:41
dhellmannasettle : how's that?19:42
dhellmannAJaeger : yeah, thanks, though19:42
asettledhellmann: I don't think I can explain how it doesn't make sense, it just doesn't say what you think it says to me :P19:42
asettleI think you might want to rephrase to something likeeeeee19:42
dhellmannasettle : that?19:42
asettle"For the context of this section, not all contributors are "developers". Contributors can refer to users, administrators, writers, operators... etc etc19:43
dhellmannyou do realize the previous wording has been in there since the beginning?19:44
dhellmannI really think people understand what contributors are19:44
asettleYeah, hahaha19:44
asettleI do.19:44
*** yamamoto has joined #openstack-doc19:45
dhellmannok, I'll spin a new version of the spec with these changes19:45
asettleYeah what you got there is good *thumbs up*19:45
dhellmannand then I'm done making changes to this :-)19:46
dhellmannit's either approvable, or we just delete all the docs!19:46
dhellmann:-)19:46
asettleI completely agree, considering you've done all the iterations19:46
asettleThank you :)19:46
asettleHahahahhaa19:46
asettleDid oyu write that in the spec?! :p19:46
asettleI appreciate that you kept "Do nothing, and watch the world burn."19:46
openstackgerritDoug Hellmann proposed openstack/docs-specs master: Adds spec for migrating the documentation suite to project repos  https://review.openstack.org/47227519:48
dhellmannsometimes stark honesty is necessary19:48
asettle:p19:50
*** vijaykc4 has quit IRC19:52
*** yamamoto has quit IRC19:52
*** dmacpher has joined #openstack-doc19:54
*** pnavarro has quit IRC20:01
*** openstackgerrit has quit IRC20:03
*** salv-orlando has joined #openstack-doc20:04
*** dmacpher has quit IRC20:07
*** fragatina has quit IRC20:07
*** gouthamr has quit IRC20:09
*** openstackgerrit has joined #openstack-doc20:10
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: add service-type redirects  https://review.openstack.org/47626220:10
*** emagana has quit IRC20:18
*** dmacpher has joined #openstack-doc20:21
*** madorn has quit IRC20:21
*** pnavarro has joined #openstack-doc20:23
*** emagana has joined #openstack-doc20:24
*** emagana has quit IRC20:28
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: move library data from openstack-projects.html to projects.yaml  https://review.openstack.org/47625220:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: delete project-specific steps from installation guide  https://review.openstack.org/47539520:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: stop generating content if a template can't be parsed or rendered  https://review.openstack.org/47625020:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: add jsonschema validation to the start of the template rendering  https://review.openstack.org/47625120:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: templatize the language-bindings page  https://review.openstack.org/47624820:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: templatize more of openstack-projects list  https://review.openstack.org/47624920:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: remove project-specific content from admin guide  https://review.openstack.org/47543520:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: move getting started content into the install guide  https://review.openstack.org/47543420:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: add a global project list file for main site templates  https://review.openstack.org/47624720:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: fix pdf build  https://review.openstack.org/47540820:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: replace install-guide landing page contents with list of projects  https://review.openstack.org/47551820:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: remove os-specific doc guide home pages  https://review.openstack.org/47551920:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: add service-type redirects  https://review.openstack.org/47626220:33
openstackgerritDoug Hellmann proposed openstack/openstack-manuals master: move /developer/.* out of the subdirectory  https://review.openstack.org/47557220:33
*** pnavarro has quit IRC20:39
*** pnavarro has joined #openstack-doc20:40
*** dmacpher has quit IRC20:44
*** gouthamr has joined #openstack-doc20:48
*** amotoki is now known as amotoki_away20:52
*** lucasxu has quit IRC20:54
*** dmacpher has joined #openstack-doc20:58
*** pnavarro has quit IRC21:11
*** dmacpher has quit IRC21:12
*** chlong has quit IRC21:22
*** dmacpher has joined #openstack-doc21:26
*** eric_young has quit IRC21:28
*** emagana has joined #openstack-doc21:28
*** catintheroof has quit IRC21:51
*** madorn has joined #openstack-doc22:02
*** salv-orl_ has joined #openstack-doc22:12
*** salv-orlando has quit IRC22:15
*** salv-orl_ has quit IRC22:15
*** salv-orlando has joined #openstack-doc22:16
*** salv-orlando has quit IRC22:21
*** dmacpher has quit IRC22:21
*** emagana has quit IRC22:34
*** dmacpher has joined #openstack-doc22:35
*** dustins_ has quit IRC22:39
*** suyog has joined #openstack-doc23:31
*** s-shiono has joined #openstack-doc23:43
*** charcol has joined #openstack-doc23:46
*** salv-orlando has joined #openstack-doc23:47
*** salv-orlando has quit IRC23:52
*** KeithMnemonic has joined #openstack-doc23:54
*** charcol-v2 has joined #openstack-doc23:59

Generated by irclog2html.py 2.15.3 by Marius Gedminas - find it at mg.pov.lt!