19:12:41 <colindixon> #startmeeting docs
19:12:41 <odl_meetbot> Meeting started Tue Mar 22 19:12:41 2016 UTC.  The chair is colindixon. Information about MeetBot at http://ci.openstack.org/meetbot.html.
19:12:41 <odl_meetbot> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
19:12:41 <odl_meetbot> The meeting name has been set to 'docs'
19:12:52 <colindixon> #topic getting started guide
19:23:59 <colindixon> #info phrobb_ asks if we could could get Beau from T-mobilie engaged in docs, he wants to work on the getting started guide
19:24:00 <colindixon> https://read-the-docs.readthedocs.org/en/latest/getting_started.html
19:24:31 <colindixon> https://read-the-docs.readthedocs.org/en/latest/builds.html
19:28:20 <phrobb_> Here's a compare/contrast of resturcturedText and markdown: http://flaviusim.com/blog/restructuredtext-vs-markdown/
19:30:51 <colindixon> #info colindixon notes that there is no real authoritative copy of the gettinger started guide right now
19:31:03 <colindixon> #info the closest thing is Denise's google doc
19:31:37 <colindixon> #info colin has a clone of that which has the tables listed as images from the AsciiDoc and is published as HTML so we had something to launch with
19:31:47 <colindixon> #info Melissa and the web team should be converting it to HTML for the main page
19:32:05 <zxiiro> https://freeseer.readthedocs.org/en/latest/
19:34:02 <colindixon> https://docs.djangoproject.com/en/1.7/ref/clickjacking/
19:37:01 <zxiiro> https://docs.readthedocs.org/en/latest/alternate_domains.html
19:38:17 <colindixon> #info the HTML version for the getting started guide hasn't yet supplanted Colin's published google doc on the dowloads page
19:38:46 <colindixon> #info colindixon says he hasn't migrated the authoritative copy to git yet because he thought we might consider moving away from AsciiDoc
19:38:52 <colindixon> #topic read the docs
19:38:57 <colindixon> #link http://readthedocs.org/
19:39:43 <colindixon> #info zxiiro says he's used it in the past and likes it
19:41:06 <colindixon> #Info it takes documentation in MarkDown and reStrucgturedText, but seems to rely on Sphinx to genearte the docs while readTheDocs basically just provides the web front end
19:41:20 <colindixon> #link https://docs.djangoproject.com/en/1.7/ref/clickjacking/ an example of something using read the docs
19:41:35 <colindixon> #info note that it flags things as as out-of-date at the top
19:41:46 <colindixon> #info it also lets you jump between versions (presumably git branches)
19:41:55 <colindixon> #info it also generates PDF versions of the full docs
19:41:59 <colindixon> #info lets you search through things
19:43:24 <colindixon> #info one thing to figure out if we can pull in live code snippets from java, it does python for now
19:44:05 <colindixon> #info colindixon notes that we only have a prototype version of that for AsciiDoc and it's not very real
19:45:53 <colindixon> #info zxiiro says that you could probably pull in docs from other git repos with a sphinx script, it could clone all projects and then pull them together
19:46:06 <colindixon> #topic next steps
19:46:37 <colindixon> #undo
19:46:37 <odl_meetbot> Removing item from minutes: <MeetBot.ircmeeting.items.Topic object at 0x2a32910>
19:46:38 <colindixon> #info colindixon notes that all of our docs are in one project so the above would just be icing on the cake
19:46:39 <colindixon> #topic next steps
19:46:55 <colindixon> #info we'd presumably want to prototype it with something
19:47:53 <colindixon> #Info it sounds like colin creating a cloned version of the docs repo jus using the getting started guide might be a good idea
19:48:03 <colindixon> #undo
19:48:03 <odl_meetbot> Removing item from minutes: <MeetBot.ircmeeting.items.Info object at 0x29d9990>
19:48:21 <colindixon> #Info it sounds like creating a cloned version of the docs repo just using the getting started guide might be a good idea
19:52:30 <colindixon> #info colindixon says his plan would be to clone docs, strip out everything but the getting started guide, converting the asciidoc to RST or markdown, doing that across branches and tags, then getting sphix/readthedocs to eat and publish it
19:53:16 <colindixon> #info risks would be making everyone move to RST or markdown instead of AsciiDoc, but that would generally be good except for the painful one-time migration
19:53:33 <colindixon> #action zxiiro volunteers to try to get *something* set up
19:55:26 <colindixon> #action zxiiro to document thigns a bit from the project's perspective, e.g., what migration would be required and how would it be different post-migratoin
19:57:19 <colindixon> #endmeeting