16:00:24 <colindixon> #startmeeting docs
16:00:24 <odl_meetbot> Meeting started Wed Jan 13 16:00:24 2016 UTC.  The chair is colindixon. Information about MeetBot at http://ci.openstack.org/meetbot.html.
16:00:24 <odl_meetbot> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:24 <odl_meetbot> The meeting name has been set to 'docs'
16:00:33 <colindixon> #topic agenda bashing
16:02:30 <colindixon> #info colindixon, denise, casey, and charles are attending
16:02:39 <colindixon> #info talk about docs patches (we're woefully behind)
16:03:47 <colindixon> #info denise wants to go over the status of trying to get SME feedback
16:04:14 <colindixon> #info denise also wants to go issues creating content
16:04:50 <colindixon> #info zxiiro wants to give a quick update on API stuff
16:05:11 <colindixon> #topic state of docs patches, reviews, and projects
16:05:53 <colindixon> #llink https://git.opendaylight.org/gerrit/#/q/project:docs+status:open+NOT+label:Code-Review%253C0 this is yet-to-be-reviewed patches for docs
16:06:17 <colindixon> #info any help would be appreciated, there are 25-30 patches, but most are small
16:08:20 <colindixon> #link https://docs.google.com/spreadsheets/d/1hci5TMUPyB6PX8Al-fwfVqvs5SQVa2wZLja_7rKWN6o/edit#gid=83290213 this is where we'll track the progress and figure out if we need to call projects out
16:08:52 <colindixon> #info colindixon is planning to put in 1-2 days of reviewing these in the next week
16:09:02 <colindixon> #topic update on API doc generation
16:09:19 <colindixon> #info zxiiro has confirmed that swagger is definitely what's running
16:10:59 <colindixon> #info zxiiro says swagger is also being provided by maven module sal-restconf-docgen is what provides the swagger stuff
16:11:26 <colindixon> #info the actual docs are hosted as a static site, which is probably good enough, but provides no actual docs
16:11:57 <colindixon> #info the feature odl-mdsal-apidocs provides the actual content, but comes from a restconf feature at the maven level
16:12:30 <colindixon> #info colindixon says the feature old-mdsal-apidocs provides docs for all YANG files that are loaded into the controller at runtime
16:13:06 <colindixon> #info the next step is probably to ping the people maintaining/writing this: ryan goulding, robert varga, and tom pantelis
16:14:20 <colindixon> #info ideally, we'd make all of this static so we can host it
16:14:41 <colindixon> #info if not, we could just do it as a swagger server
16:15:02 <colindixon> #topic JavaDoc generation
16:15:27 <colindixon> #info zxiiro finalized a patch to YANG tools which shows how to generate a maven site with JavaDoc there along with documentation for how to do that
16:15:30 <zxiiro> #link https://git.opendaylight.org/gerrit/27711 Enable javadoc / maven-site for yangtools
16:16:05 <colindixon> #info colindixon asks why it failed verification
16:17:12 <colindixon> #info there are two things you need to do: make the same change to all pom files to get maven sites, and then make a more complex change to the root pom file
16:17:40 <colindixon> #info there are more failures for Java 8 javadoc stuff with this than with other tools
16:18:11 <colindixon> #info actual failures are that it doesn't build with maven 3.1, but this shoudl be YANG tools only as all other projects use something different
16:18:32 <colindixon> #action colindixon to ping anipbu and ask if we should start migrating to this to generate sites for all projects before Beryllum release
16:19:55 <colindixon> #info colindixon asks if we could get autorelease to build a single maven site with all of Beryllium's javadoc
16:20:15 <colindixon> #info zxiiro says yes and it might fix cross-project javadoc links
16:21:37 <colindixon> #info colindixon asks if these instructions will work for autorelease or we'll need to change things, zxiiro says we should probably try with two projects in autorelease first
16:22:15 <colindixon> #action zxiiro to talk to yangtools about removing maven 3.1 support to get this merged and then find a second project that we could play with, likely mdsal
16:24:05 <colindixon> #info anipbu asks if this is really possible given that it's M5 already
16:24:38 <colindixon> #info colindixon and zxiiro say it should be <1 hour of work, but it might still be hard
16:24:56 <colindixon> #info anipbu says that he's pessimistic about getting it into Beryllium at this point
16:26:38 <colindixon> #info zxiiro notes that this is basically because we don't use maven directory structure the way it expects
16:26:48 <colindixon> #info zxiiro says that he could generate a script that woudl do this with the pom file, which would be easy
16:27:37 <colindixon> #info the harder part is fixing javadoc, but that can be (at least partially disabled) to avoid running the linter, it fixed some, but not all of the issues in yangtools
16:29:00 <colindixon> #info colindixon asks if we could somehow manually generate javadoc from autorelease for Beryllium to get *something*
16:30:35 <colindixon> #info colindixon says it woudl be huge if we could host the javadoc and swagger for Beryllium, we definitely need to do this in Boron
16:30:44 <colindixon> #action colindixon to add this as a requirment for Boron
16:31:06 <colindixon> #action colindixon or zxiiro to look into manually generating javadoc from autorelease instead of using maven sites in Beryllum
16:31:09 <colindixon> #topic
16:31:14 <colindixon> #undo
16:31:14 <odl_meetbot> Removing item from minutes: <MeetBot.ircmeeting.items.Topic object at 0x1fd0810>
16:31:34 <colindixon> #topic getting feedback from SMEs
16:32:04 <colindixon> #info when a tech writer comes onto a project, the assumtion is not that that they have technical knowledge of the project
16:32:14 <zxiiro> colindixon: sorry gotta drop. got some fires to take care of
16:32:32 <colindixon> #info instead, the assumption is taht there will be subject matter experts (SMEs) to review, give feedback, sanity check, etc. the documentation
16:32:36 <colindixon> zxiiro: thanks for staying
16:33:26 <colindixon> #info denise says this is getting to be hard to get feedback
16:34:03 <colindixon> #info denise says the projects are actually pretty good about this, instead the biggest problem is getting feedback from phrobb and colindixon
16:34:13 <colindixon> #Info denise asks if there are others who can fill that role
16:37:21 <colindixon> #info colindixon suggests anipbu as another person
16:38:19 <colindixon> #info colindixon says let's see how phrobb, colindixon, and anipbu work for reviewing things and then have denise yell at us if we don't respond fast enough
16:39:43 <colindixon> #info denise says she literally goes over phrobb's house and sits in his office to get time with him, and that helps
16:41:33 <colindixon> #topic documentation wiki page
16:41:58 <colindixon> #link https://wiki.opendaylight.org/view/Docucentral casey asks people to go here and see what this looks like
16:42:22 <colindixon> #info casey asks if we should have a centralized place for people to find documentation
16:43:08 <colindixon> #info colindixon says we should have a centralized place, but he's not sure if the wiki or docs.opendaylight.org or opendaylight.org/docs would work best
16:44:46 <colindixon> #action colindixon to add a link saying "if you're looking for actual documentation, go here" to the top of the docs project page to get people to right place
16:45:19 <colindixon> #info colindixon says the current content we have is: getting started guide, developer guide, user guide, openstack guide
16:45:41 <colindixon> #info we're hoping to have API docuemntation both for JavaDoc and for YANG/RESTCONF
16:51:13 <colindixon> #info case says we do need the rest of the content, colindixon says generating that content will be hard for things like admin guides for all projects for all projects for all OSes
16:54:24 <colindixon> #info anipbu points out (a) we will guides guide per release and (b) we currently say contributor documentation should live on the wiki
16:55:57 <colindixon> #info colindixon agrees that we need some way to have multiple guides, either with subpages or with multiple entries per guide
16:57:28 <colindixon> #Info colindixon says for now having contributor docs on the wiki where they actually are likely to be updated
17:00:01 <colindixon> #info colindixon says he'd like to have one page (maybe even non-wiki) that goes over project-agnositc cotrtibutor docs, and then project-specific info on project main pages (maybe as part of the template)
17:00:09 <colindixon> #topic project categorization
17:00:26 <colindixon> #action colindixon to try to work on getting project categorization for this page https://wiki.opendaylight.org/view/Project_list
17:01:25 <colindixon> #info colindixon says his plan would be to (a) come up with categories, (b) ask projects to add those categories as they see fit to their homepage with multiple categories being allowed, (c) use those categories to generate lists on the project list page
17:01:51 <colindixon> #info anipbu asks if we need to reconcile these categories with the TSC election categories, colindixon and casey say probably, but that shoudl be doable
17:01:54 <colindixon> #endmeeting