06:00:29 <loquacities> #startmeeting docinstallteam
06:00:30 <openstack> Meeting started Tue Jul  5 06:00:29 2016 UTC and is due to finish in 60 minutes.  The chair is loquacities. Information about MeetBot at http://wiki.debian.org/MeetBot.
06:00:31 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
06:00:33 <openstack> The meeting name has been set to 'docinstallteam'
06:00:38 <loquacities> hi ildikov :)
06:00:54 <ildikov> hi :)
06:01:04 <loquacities> anyone else here?
06:01:05 <AJaeger> morning
06:01:09 <loquacities> hi AJaeger
06:01:10 <katomo> hi loquacities
06:01:13 <loquacities> hi katomo
06:01:16 <strigazi> Spyros Trigazis (magnum)
06:01:20 <loquacities> hi strigazi
06:01:32 <loquacities> that looks like a quorum to me, let's get started :)
06:01:42 <loquacities> #topic Draft index page
06:01:52 <loquacities> #link https://review.openstack.org/#/c/331704
06:02:02 <loquacities> this is the current patch for the draft index page
06:02:25 <AJaeger> thanks for that page. It's something to get us started but far too long. You miss the different OSes.
06:02:28 <loquacities> you can see the built pages here: http://docs-draft.openstack.org/04/331704/4/check/gate-openstack-manuals-tox-doc-publish-checkbuild/9c63720//publish-docs/www/draft/draft-index.html and here http://docs-draft.openstack.org/04/331704/4/check/gate-openstack-manuals-tox-doc-publish-checkbuild/9c63720//publish-docs/www/project-install-guide/draft/index.html
06:02:38 <loquacities> AJaeger: yes, i agree
06:02:47 <loquacities> but i also think we need to merge *something*
06:02:52 <loquacities> we can't bikeshed on this forever
06:03:23 <AJaeger> loquacities: I'm fine with merging now - and refine then.
06:03:41 <AJaeger> But if we merge now, let's put an item on our todo list: Rework index page ;)
06:03:49 <loquacities> yes, i think that's a good plan
06:03:53 <katomo> +1
06:03:56 <loquacities> all those in favour say aye?
06:04:10 <strigazi> +1
06:04:20 <loquacities> #action AJaeger to merge #331704
06:04:26 <ildikov> +1 to get progress and refine later :)
06:04:34 <loquacities> #action loquacities to add 'refine index page' to to do list
06:04:41 <loquacities> awesome, thanks everyone
06:04:57 <loquacities> #topic Use of the ``only`` directive
06:05:05 <loquacities> #link http://lists.openstack.org/pipermail/openstack-docs/2016-July/008804.html
06:05:13 <loquacities> i'd like to get some opinions on this
06:05:37 <loquacities> i can see how restricting use of only can make life a lot easier for us
06:05:50 * AJaeger said everything in his emails - or should I state again here?
06:06:03 <loquacities> AJaeger: hopefully everyone has read the thread
06:06:12 <ildikov> I've worked on the Ceilometer content and we have quite many files and I didn't even add Debian as we didn't have instructions for that in many places
06:06:32 <loquacities> what i'm mainly concerned about is how many projects will want to use only, and will us saying not to use it make life difficult for everyone?
06:06:45 <ildikov> so for some projects we might think about proposing structure as well as if someone just adds all the files that will be a mess
06:07:13 <loquacities> ildikov: proposing a structure that uses only?
06:07:28 <ildikov> loquacities: no a structure if we remove only
06:07:33 <loquacities> oh, right
06:07:37 <strigazi> ildikov: can share some patches to see the files?
06:07:51 <ildikov> loquacities: I mean how to organize the files in a digestible way kind of thing
06:07:58 <loquacities> right, that makes sense
06:08:22 <loquacities> isn't that what the cookiecutter already does, though?
06:08:27 <AJaeger> the coookiecutter template does not use only - so that's one structure to use.
06:08:38 <ildikov> #link https://review.openstack.org/#/c/330051/
06:08:51 <ildikov> sorry, it wasn't handy, the Ceilo files ^
06:08:51 <loquacities> is the cookiecutter structure not sufficient?
06:09:00 <strigazi> ildikov: thx
06:09:58 <ildikov> loquacities: I'll check the latest
06:10:10 <loquacities> ok
06:10:38 <loquacities> so, is the sensible path forward to say no ``only`` for now, and let's review in six months?
06:10:49 <ildikov> loquacities: my only concern is that it's not always easy to get people update the docs and if they don't feel comfortable as the structure is not straight forward then it's not really a win either
06:10:57 <loquacities> just to simplify things for us at least in the short term while we find our feet
06:11:13 <loquacities> ildikov: is the cookiecutter structure not appropriate then?
06:11:17 <loquacities> do we need to work on that some more?
06:11:31 <ildikov> loquacities: from build job, etc. perspective it's fine to remove "only"
06:11:37 <loquacities> right
06:11:41 <ildikov> loquacities: I'll check and come back if I have any better idea
06:11:51 <loquacities> ok
06:12:14 <loquacities> do we have a consensus on cutting out only use for now, and reviewing later?
06:12:21 <strigazi> ildikov: if you put the files in dirs? would that help? eg one dir for install-nove
06:12:26 <ildikov> loquacities: let's leave it how it is now and iterate if I or anyone else has suggestions as I'm not even sure it's good enough how the Ceilometer structure looks right now
06:12:28 <AJaeger> ildikov: Yes, I agree with the straightforward structure. I fear with using only it gets more complex. loquacities, could you review the current structure and see whether we can make it better, please?
06:12:29 <strigazi> loquacities: +1
06:12:35 <loquacities> #action ildikov to review cookiecutter structure
06:12:46 <ildikov> strigazi: I have folders already
06:12:52 <loquacities> #action loquacities to review cookiecutter structure
06:12:54 <loquacities> sure :)
06:13:12 <strigazi> ildikov: oh yes, sorry
06:13:15 <loquacities> maybe we should get a good IA involved here too. darrenc maybe, if he has time?
06:13:32 <ildikov> AJaeger: yeah, I think what we can do here is to choose one option and get the best out of it
06:13:37 <loquacities> ok, so i think we have a plan of action here, anyway
06:13:56 <loquacities> i'll update the ML with a 'don't use only for now' message, and add it to my newsletter this week
06:14:07 <loquacities> and we can review the cookiecutter to see if we can improve it
06:14:14 <ildikov> AJaeger: mixing up the two looks messy, I think we all agree on that
06:14:20 <loquacities> +1
06:14:44 <katomo> +1
06:14:48 <loquacities> #action loquacities to message about not using only
06:14:49 <AJaeger> ildikov: I don't want to mix them up, no worries.
06:15:44 <ildikov> AJaeger: I just raise my concerns here as I don't want to be the only person updating the Ceilo install guide for the rest of my life as others don't get the structure, but I might just overcomplicate it :)
06:16:06 <loquacities> ildikov: you need an apprentice!
06:16:09 <ildikov> AJaeger: coolio :)
06:16:38 <AJaeger> ildikov: that's why I'm happy to hear that others will take a look at your change and cookiecutter - we need to keep it simple.
06:16:44 <ildikov> loquacities: good idea
06:17:05 <loquacities> ok, final thing on the agenda ...
06:17:09 <loquacities> #topic work items
06:17:18 <loquacities> #link https://wiki.openstack.org/wiki/Documentation/InstallGuideWorkItems
06:17:28 <loquacities> i've gone through and updated this, and we're a good way through the list now
06:17:35 <ildikov> AJaeger: agreed, tnx
06:18:08 <loquacities> AJaeger: what needs to be done on the ops:docs:install-guide tag ?
06:18:45 <AJaeger> loquacities: somebody needs to talk with operators or with Tom Fifield directly.
06:19:13 <loquacities> well, thingee has his name up there
06:19:17 <loquacities> maybe we should reach out to him?
06:19:26 <AJaeger> loquacities: the operators are in charge of that tag.
06:19:36 <loquacities> hrm, ok
06:19:42 <AJaeger> loquacities: if it's his name, then try him first;)
06:19:47 <loquacities> heh
06:20:02 <loquacities> ok, i might send mail, but i'll copy you in because i don't fully understand what needs to happen here
06:20:07 <ildikov> they should get together this week I think due to OpenStack Days in that area
06:20:26 <loquacities> i think that and the testing scripts are about all that's left on this list that hasn't been started now
06:20:30 <ildikov> so if you can reach out to them they might get a chance to discuss it face to face, I mean Mike and Tom
06:20:32 <loquacities> which is pretty awesome, really
06:20:38 <loquacities> ildikov: oh, good plan
06:20:46 <loquacities> i'll send that email today before i finish, then
06:21:45 <ildikov> coolio :)
06:22:22 <strigazi> loquacities: about the launch an instance section
06:22:31 <loquacities> yes?
06:22:49 <strigazi> I sent an email the other day, should I push in openstack manuals
06:22:58 <strigazi> or we are going to move that section as well?
06:23:11 <strigazi> to project repos
06:23:17 <loquacities> i think i missed this email, sorry
06:23:24 <AJaeger> strigazi: Why do you want to move it?
06:23:34 <loquacities> ah, found it
06:23:49 <loquacities> it got lost in all the only emails ;)
06:23:57 <AJaeger> It fits IMHO perfectly into what we have...
06:24:10 <strigazi> ok
06:24:12 <AJaeger> For magnum, I guess, you'll want to have a sepcific "launch a container" section.
06:24:24 <loquacities> that would be considered core services, i think ...
06:24:45 <strigazi> it's launch a COE :)
06:25:51 <strigazi> loquacities: so what I should do?
06:26:03 <strigazi> push in our repo?
06:26:17 <loquacities> i think AJaeger is right to leave it where it is
06:26:29 <loquacities> in our repo
06:26:36 <AJaeger> strigazi: push it in your repo - and I suggest that we revisit this in a couple of weeks again and see how it looks like.
06:27:00 <strigazi> under install-guide?
06:27:04 <AJaeger> IMHO we need the complete guide first up and then might need to consolidate
06:27:16 <loquacities> right
06:27:19 <AJaeger> strigazi: yes, under install-guide
06:27:19 <strigazi> AJaeger: makes sense
06:27:38 <loquacities> any other businesS?
06:28:04 <ildikov> we discussed one more topic in the mails last week
06:28:19 <ildikov> which was how to organize docs in the project repos
06:28:51 <ildikov> we agreed on having the install-guide folder and the doc folder co-existing
06:28:58 <loquacities> oh, right, yeah
06:29:17 <loquacities> yeah, moving everything under /doc is appealing, but i think it's a huge scale change
06:29:18 <ildikov> I think it would be good to revisit this later as well and try to have one doc folder
06:29:36 <ildikov> we can have this as a cross-project topic
06:29:43 <loquacities> probably sensible
06:29:52 <katomo> yeah
06:30:01 <ildikov> but as I said in the mails it's not that urgent, although I think it would be beneficial long term
06:30:10 <AJaeger> ildikov: My assumption is that we have several books - developer guides, install-guide, api-ref.
06:30:19 <AJaeger> Each of them gets published to a different place.
06:30:29 <katomo> ildikov: +1
06:30:37 <AJaeger> So, we cannot have a single doc/source directory to publish all of them with one sphinx invocation.
06:31:10 <AJaeger> doc/source for developer docs;doc/install-guide;doc/api-ref; looks very strange to me.
06:31:13 <ildikov> AJaeger: I guess we can have a doc/<name-of-teh-guide>/source or something similar structure
06:31:32 <AJaeger> And I don't want to rename developer docs - accross all OPenStack repos...
06:31:43 <loquacities> yeah, that's my main concern too
06:31:59 <AJaeger> So, this would work: doc/developer for developer docs;doc/install-guide;doc/api-ref - but that's a lot rename from doc/source to doc/developer/source
06:32:08 <ildikov> AJaeger: openstack manuals is using mostly sphinx as well and has a good structure
06:32:25 <AJaeger> ildikov: but has not doc/source
06:32:29 <katomo> hmmm...
06:32:38 <ildikov> AJaeger: I understand your concern, but it's not a big restructuring, although in lots of repos
06:33:06 <ildikov> if we consider moving more content to project trees, then I still think one folder is more reasonable
06:33:16 <AJaeger> ildikov: If you get it done, I'm happy to review - but this is task that I don't want to push ;)
06:33:19 <ildikov> but we don't necessarily have to solve this today
06:33:46 <loquacities> heh
06:33:55 <AJaeger> ildikov: yes, it's only a move - if we change anything we need to see how it integrates with CI scripts and how to have consistency accross repos
06:34:09 <ildikov> AJaeger: I'm happy to at least try and if we get too much push back then we can be relaxed that it's a community decision :)
06:34:10 <loquacities> +1
06:34:41 <loquacities> i think this needs to be brought up in a cross-project meeting
06:34:42 <AJaeger> ildikov: go for it ;) But let's not block us on this, please (and I don't see us blocking right now)
06:34:52 <ildikov> AJaeger: of course, my plan wasn't to secretly ruin the whole docs build ;)
06:34:55 <loquacities> although i never seem to get to those any more ...
06:34:58 <ildikov> AJaeger: so +1 on that
06:35:01 <loquacities> lol
06:35:32 <loquacities> #topic open discussion
06:35:44 <loquacities> anything else?
06:36:01 <ildikov> AJaeger: again, I think it's more a long term task, so I'll try to put some plan together and we can discuss it on the next Summit also as a cross-project topic maybe
06:36:06 <AJaeger> loquacities: which chapters still need moving to project repos?
06:36:28 <loquacities> swift, and manila, i think?
06:36:38 <loquacities> https://review.openstack.org/#/c/330070/
06:36:43 <loquacities> https://review.openstack.org/#/c/317152/
06:37:30 <strigazi> Yes, that is all
06:37:31 <AJaeger> manila uses only AFAIU.
06:38:08 <loquacities> ah
06:38:36 <katomo> ToT
06:39:04 <AJaeger> hope that those two will be merged for our next meeting. I suggest to help reviewing - and ping for core reviews once we're happy.
06:39:06 <loquacities> ah, yes, it does
06:39:30 <loquacities> do we need to discuss this with goutham?
06:40:40 <loquacities> will it be a problem having only in there?
06:42:09 <katomo> become complex...
06:42:36 <AJaeger> loquacities: do you want to open the discussion from earlier again? I thought we had consensus to not use only for now - and revisit later
06:42:48 <loquacities> well, that's my point
06:43:03 <loquacities> we have consensus to not use it, so why should we merge the manila patch?
06:43:10 <loquacities> shouldn't we be asking goutham to remove it?
06:43:24 <AJaeger> loquacities: Oh, I misunderstood you -yes, we should ask him.
06:43:44 <katomo> ah
06:44:13 <loquacities> ok, i'll reach out to him
06:44:21 <AJaeger> thanks
06:44:25 <katomo> thanks
06:44:25 <loquacities> np
06:44:39 <loquacities> #action loquacities to chat to goutham about use of only in manila patch 317152
06:44:46 <loquacities> ok, anything else?
06:44:58 <loquacities> or can i give you 16 minutes back
06:45:01 <loquacities> ?
06:45:09 <AJaeger> 15 mins, please ;)
06:45:11 <katomo> nothing from me.
06:45:17 <loquacities> yay!
06:45:20 <ildikov> :)
06:45:26 <loquacities> thanks for attending everyone :)
06:45:27 <katomo> we get 15 mins !
06:45:29 <strigazi> bye
06:45:32 <loquacities> #endmeeting