19:01:00 <catherineD> #startmeeting refstack
19:01:01 <openstack> Meeting started Tue Mar 21 19:01:00 2017 UTC and is due to finish in 60 minutes.  The chair is catherineD. Information about MeetBot at http://wiki.debian.org/MeetBot.
19:01:02 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
19:01:05 <openstack> The meeting name has been set to 'refstack'
19:01:38 <rockyg> o/
19:02:12 <catherineD> waves at rockyg:
19:02:25 <hogepodge> o/
19:02:27 <catherineD> #link meeting agenda and notes,  https://etherpad.openstack.org/p/refstack-meeting-17-03-21
19:02:34 * rockyg waves back
19:03:05 <pvaneck> o/
19:04:08 <catherineD> Anne Gentle said sh will attend today's meeting ...  we can discuss other subject first
19:04:22 <mguiney> o/
19:04:44 <catherineD> #topic     RefStack is now on StoryBoard
19:05:12 <catherineD> Thanks to hogepodge: and the OpenStack team ..
19:05:25 <catherineD> #link     RefStack is now on StoryBoard  (  https://storyboard.openstack.org/#!/project/878 )
19:06:01 <catherineD> please use StoryBoard instead of Launchpad from now on ..
19:06:41 <catherineD> Let's skip over the documentation topic and revisit later ..
19:06:50 <hogepodge> Happy to help
19:06:50 <catherineD> #topic Update existing certified data with the verified flag
19:07:04 <catherineD> mguiney: any update?
19:07:44 <mguiney> yes! i actually just finished up a few formatting fixes, and am ready to push a version for testing
19:08:09 <catherineD> mguiney: great thank you ..
19:08:33 <mguiney> but before I do that, I figured I would check up on where I should be pushing it. refstack/tools, correct?
19:09:00 <catherineD> mguiney: yes
19:09:39 <catherineD> moving on?
19:10:09 <mguiney> cool, thank you
19:10:21 <catherineD> alright ..
19:10:32 <catherineD> #topic Pending reviews
19:10:45 <catherineD> #topic     Change doc references from DefCore to Interop Working Group  (  https://review.openstack.org/#/c/390881/  )
19:11:16 <luzC> o/
19:11:21 <catherineD> hogepodge: Is OpenStack Powered a TM?
19:11:40 <hogepodge> yes
19:12:16 <hogepodge> It has an associated work mark and logo mark.
19:12:36 <catherineD> ic
19:13:47 <catherineD> do you have a link?  I would like to use the same format at RefStack?
19:15:09 <catherineD> that is "is TM the same size as OpenStack " or is it a superscript or subscript ?
19:17:04 <hogepodge> I don't know 100%, especially since we're updating the identity
19:17:40 <catherineD> ok we still have time ...
19:17:44 <catherineD> moving on ..
19:17:54 <luzC> if I understand correctly... for this patch I need to change text from "OpenStack Powered (TM) Guidelines" to "OpenStack Powered <special_TM_sign> Guidelines"??
19:18:02 <luzC> is that correct?
19:18:29 <luzC> just checking to add the resolution as a comment
19:18:42 <rockyg> I think all the info and jpg's are on the o.o website
19:18:57 <catherineD> yes if html can tolerate the <special_TM_sign >
19:19:33 <hogepodge> I wouldn't worry about it, tbh. We're much more flexible on community driven work, and are mainly looking for commercial trademark violations. I also don't know if you would want to use R or TM, I think we're using R on the OpenStack logo
19:19:35 <catherineD> At the minumum we confirm at this meeting that "OpenStack Powered" is a TM
19:21:22 <catherineD> the phase "OpenStack Powered (TM) Guidelines" with all charactoer of the same sizes looks  odd at my test system .. that is why I am thinking of whether we should do something different
19:21:29 <catherineD> but it is just cosmetic
19:22:08 <luzC> sounds good, I'll fix it
19:22:19 <rockyg> (TM) is usually superscript on words
19:22:26 <catherineD> luzC: we are not sure what ot fix yet :-)
19:22:46 * catherineD waves at annegentle:
19:22:57 * annegentle waves
19:23:14 <catherineD> but it just look odd on the UI with the TM being the same size
19:23:44 <catherineD> rockyg: hogepodge:  should we do superscript then?
19:24:05 <rockyg> annegentle, knows a lot about this kinda stuff.
19:24:06 <hogepodge> sub or super, we use sub on the logo
19:24:27 * annegentle got on vpn and lost irc
19:24:31 <annegentle> that's how it goes some days :)
19:24:55 <rockyg> "OpenStack Powered (TM) Guidelines"  sub or superscript for TM?
19:25:06 <catherineD> alright great we will use sub to be consistent
19:25:11 <annegentle> whatever the lawyers say
19:25:12 <annegentle> :)
19:25:16 <catherineD> rockyg: yes
19:25:29 <catherineD> luzC: now we have a fix :-)
19:25:32 <luzC> :)
19:25:49 <catherineD> great moving on ...
19:26:25 <catherineD> annegentle: thx for attending this IRC and your inputs ..
19:26:40 <annegentle> yes, happy to help
19:26:44 <catherineD> #topic RefStack documentation
19:27:20 <catherineD> BTW this is the agenda link for tomday's meeting https://etherpad.openstack.org/p/refstack-meeting-17-03-21
19:28:12 <catherineD> the discussion is to map out the pro and con of publishing RefStack doc at RefStack site or OpenStack doc site ..
19:28:40 <annegentle> well, and it is more matrixed than that, really I see two docs sites
19:28:57 <annegentle> pros and cons of two decisions possibly
19:28:59 <catherineD> the most important RefStack requirement is the source information has to be one place ..
19:29:49 <annegentle> sure, just saying there are two audiences
19:29:59 <annegentle> so I would encourage two sources
19:30:26 <annegentle> since there are two publishing platforms
19:30:31 <catherineD> annegentle: the 2 sources with different content right?
19:30:33 <annegentle> sorta working backwards from the problem
19:30:35 <annegentle> yeah
19:30:53 <annegentle> and to me the harder problem is the end-user situation
19:32:16 <catherineD> audience #1: Refstack users (those are the people who run tests and uploading them )?
19:32:19 <annegentle> feel free to tell me that's wrong, that you actually need to onboard more contributors
19:32:30 <catherineD> audience #2: RefStack developers?
19:32:41 <annegentle> yep
19:33:10 <annegentle> people who want to contribute to: well, you tell me, refstack the app or refstack tests?
19:33:14 <catherineD> annegentle: we do need to onboard more contributors .. you are correct
19:33:24 <annegentle> do you have a priority?
19:34:14 <catherineD> I think the priority is RefStack users ..
19:34:30 <annegentle> yeah, I'd agree... being one myself :)
19:35:01 <catherineD> annegentle: :-)
19:35:28 <hogepodge> yes, end users are struggling
19:35:36 <catherineD> so for RefStack users the preference is to host those document at RefStack?
19:35:53 <hogepodge> it would be much easier for me
19:36:16 <annegentle> catherineD I think so, that's where I started and the user experience/navigation was tough
19:36:28 <hogepodge> sending someone to the git repo right away can be fraught, especially if we're sending them to cgit.openstack.org (which is ugly)
19:36:56 <annegentle> hogepodge yeah cgit doesn't have an HTML rendering
19:37:08 <annegentle> hogepodge but those are going to github iirc
19:37:18 <annegentle> hogepodge still... no overarching nav that way which is what I found hard
19:37:32 <hogepodge> github has better rendering, but is fraught politically within openstack
19:37:48 <annegentle> hogepodge right
19:37:54 <catherineD> we know that if hosting at RefStack we won't be able to use sphnix as is
19:38:04 <pvaneck> Just to provide a little update regarding displaying some of the info from the rst docs onto the refstack website...
19:38:13 <pvaneck> I was playing around with docutils, and it is doable to convert the rst to html, then use python to extract the content from the html body tags so that we have simple html that can be used as angular templates. Then it is just a matter of tabulating all these templates on the about page.
19:38:30 <annegentle> catherineD yes, that's true, and I have no experience with ngdocs to do any pre-analysis
19:38:49 <catherineD> that RefStack document will be one-off and deviate from the rest of  OpenStack project
19:40:20 <catherineD> pvaneck: when will the conversion take place ( rst -> html_)
19:40:36 <annegentle> catherineD well, not to put too fine a point on it, but the app is already, hence the need for ngdocs to better integrate
19:40:54 <annegentle> with the app itself
19:41:37 <annegentle> catherineD I see it like this -- it's like if we did more embedded docs for Horizon, embedded strings would need to fit into the horizon dashboards and may need to be written a certain way.
19:42:09 <annegentle> it's also possible ngdocs isn't a great solution, really pvaneck may have good ideas for best integration/user experience, might be flat HTML files
19:42:24 <catherineD> I take a quick look at ngdocs ... one of the different that stand out for me is that the ngdos would be hard to ready at the repository .. where as rst being convert tand easier to read
19:42:48 <catherineD> hard to read ..
19:43:00 <annegentle> catherineD well, that may only be due to your familiarity and GitHub's rendering.
19:43:26 <catherineD> annegentle: yea
19:43:30 <annegentle> catherineD not to discount that first viewpoint, of course, but that I think the better end-goal is a beautiful doc on the app itself.
19:43:46 <annegentle> catherineD so then the first viewpoint is "wow, gorgeous" :)
19:43:59 <pvaneck> catherineD: most likely puppet will run whatever conversion script/tool we use
19:44:16 <pvaneck> i can create a mockup with our current docs to show how it would look
19:44:30 <annegentle> pvaneck have you tried ngdocs? much of a pain to learn? Or okay?
19:45:29 <pvaneck> for general javascript documentation, i think i have just been using jsdoc
19:46:40 <annegentle> pvaneck yeah I think ngdocs is an offshoot? Subshoot? Not sure what the enveloper is :)
19:46:53 <pvaneck> ngdoc for full fledged informational documentation would still need a conversion tool/script to htmlize it for website displayal
19:47:29 <annegentle> (ngdoc is a flavor of jsdoc) and yeah, that's where the puppet scripts come in right
19:47:58 <annegentle> pvaneck or, did you find you could integrate HTML built from RST/Sphinx?
19:48:53 <pvaneck> annegentle: in my simple testing, i found i could use doctools/sphinx to create html templates that should be able to integrate okay.
19:49:11 <annegentle> I think that was the other approach you were gonna look into, yeah.
19:49:29 <annegentle> pvaneck I think that's a good approach, then, to get integratable HTML
19:49:37 <annegentle> I can't spell :)
19:50:16 <pvaneck> annegentle: catherineD: yea, seems straightforward. I will create a mockup
19:50:31 <annegentle> pvaneck catherineD excellent.
19:50:38 <catherineD> so I think the first ageement we have here is that the RefStack user doc should be published at the RefStack site and this is the priority .. and we knoiw  that we will be using one-off doc for this
19:51:33 <annegentle> nice, and I think the four-page starter set is a decent start
19:51:43 <catherineD> pvaneck: will create a mockup and we will evaluvate this approach vs ngdocs
19:51:51 <mguiney> should I update the spec?
19:52:10 <annegentle> mguiney yeah, good thinking
19:52:19 <luzC> catherineD also does documentation should be reviewed, maybe refactored to divide the things that belong to users?
19:52:43 <catherineD> luzC: I am thinking that if we use pvaneck: 's approach
19:52:51 <catherineD> the source will be in RST
19:53:15 <catherineD> I do not see why we should not publish the doc on both places?
19:53:20 <annegentle> luzC I think the idea is to put end-user docs in the refstack app repo, and is that separate from the other repo?
19:54:03 <catherineD> end-user doc for sure will be published to the refstack site ...
19:54:32 <annegentle> I was thinking of refstack repo for end-user docs, refstack-client for contributor docs, but that might be backwards
19:54:59 <catherineD> if we go the ngdocs route we definitely need to separate the 2 sources
19:55:39 <annegentle> catherineD we also in other projects use separate directories and separate conf.py files, so all in same repo but different deliverables.
19:55:56 <catherineD> annegentle: oh  .. I was thinking of the RefStack user doc (at refstack site ) and the developer doc (at the openstack doc site)
19:55:59 <annegentle> catherineD so it's not an unknown pattern...
19:56:16 <catherineD> annegentle: that is great ..
19:56:32 <catherineD> luzC: your thoughts?
19:56:37 <annegentle> catherineD yeah we can publish to docs.openstack or developer.openstack from one repo
19:56:56 <annegentle> luzC I don't know the content itself well enough to know what needs to be split out.
19:57:11 <annegentle> luzC catherineD let me find an example of two folders in one repo for two docs
19:57:23 <catherineD> luzC: so we still need all the reviews that you have created ...
19:57:29 <catherineD> annegentle: ++
19:57:51 <catherineD> ok 3 mininutes left
19:58:14 <luzC> yes, agree... just don't remember the exact content of the documentation...
19:58:20 <luzC> :)
19:58:30 <annegentle> luzC yep :)
19:58:51 <catherineD> #agreed  RefStack user doc should be published at the RefStack site and this is the priority .. and we know  that we will be using one-off doc for this
19:59:15 <catherineD> annegentle: thank you so much for giving your time here ...
19:59:33 <annegentle> sure, sorry for being late!
19:59:35 <catherineD> We know what to do next ...
19:59:47 <annegentle> great, please feel free to add me to any reviews
19:59:49 <catherineD> annegentle: no perfect timing ..
20:00:13 <catherineD> thank you all .. see you next time ..
20:00:23 <catherineD> luzC: thx for all the doc patches ..:- )
20:00:38 <catherineD> #endmeeting