#opendaylight-docs: docs

Meeting started by colindixon at 16:00:24 UTC (full logs).

Meeting summary

  1. agenda bashing (colindixon, 16:00:33)
    1. colindixon, denise, casey, and charles are attending (colindixon, 16:02:30)
    2. talk about docs patches (we're woefully behind) (colindixon, 16:02:39)
    3. denise wants to go over the status of trying to get SME feedback (colindixon, 16:03:47)
    4. denise also wants to go issues creating content (colindixon, 16:04:14)
    5. zxiiro wants to give a quick update on API stuff (colindixon, 16:04:50)

  2. state of docs patches, reviews, and projects (colindixon, 16:05:11)
    1. any help would be appreciated, there are 25-30 patches, but most are small (colindixon, 16:06:17)
    2. 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 (colindixon, 16:08:20)
    3. colindixon is planning to put in 1-2 days of reviewing these in the next week (colindixon, 16:08:52)

  3. update on API doc generation (colindixon, 16:09:02)
    1. zxiiro has confirmed that swagger is definitely what's running (colindixon, 16:09:19)
    2. zxiiro says swagger is also being provided by maven module sal-restconf-docgen is what provides the swagger stuff (colindixon, 16:10:59)
    3. the actual docs are hosted as a static site, which is probably good enough, but provides no actual docs (colindixon, 16:11:26)
    4. the feature odl-mdsal-apidocs provides the actual content, but comes from a restconf feature at the maven level (colindixon, 16:11:57)
    5. colindixon says the feature old-mdsal-apidocs provides docs for all YANG files that are loaded into the controller at runtime (colindixon, 16:12:30)
    6. the next step is probably to ping the people maintaining/writing this: ryan goulding, robert varga, and tom pantelis (colindixon, 16:13:06)
    7. ideally, we'd make all of this static so we can host it (colindixon, 16:14:20)
    8. if not, we could just do it as a swagger server (colindixon, 16:14:41)

  4. JavaDoc generation (colindixon, 16:15:02)
    1. 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 (colindixon, 16:15:27)
    2. https://git.opendaylight.org/gerrit/27711 Enable javadoc / maven-site for yangtools (zxiiro, 16:15:30)
    3. colindixon asks why it failed verification (colindixon, 16:16:05)
    4. 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 (colindixon, 16:17:12)
    5. there are more failures for Java 8 javadoc stuff with this than with other tools (colindixon, 16:17:40)
    6. 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 (colindixon, 16:18:11)
    7. ACTION: colindixon to ping anipbu and ask if we should start migrating to this to generate sites for all projects before Beryllum release (colindixon, 16:18:32)
    8. colindixon asks if we could get autorelease to build a single maven site with all of Beryllium's javadoc (colindixon, 16:19:55)
    9. zxiiro says yes and it might fix cross-project javadoc links (colindixon, 16:20:15)
    10. 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 (colindixon, 16:21:37)
    11. 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 (colindixon, 16:22:15)
    12. anipbu asks if this is really possible given that it's M5 already (colindixon, 16:24:05)
    13. colindixon and zxiiro say it should be <1 hour of work, but it might still be hard (colindixon, 16:24:38)
    14. anipbu says that he's pessimistic about getting it into Beryllium at this point (colindixon, 16:24:56)
    15. zxiiro notes that this is basically because we don't use maven directory structure the way it expects (colindixon, 16:26:38)
    16. zxiiro says that he could generate a script that woudl do this with the pom file, which would be easy (colindixon, 16:26:48)
    17. 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 (colindixon, 16:27:37)
    18. colindixon asks if we could somehow manually generate javadoc from autorelease for Beryllium to get *something* (colindixon, 16:29:00)
    19. colindixon says it woudl be huge if we could host the javadoc and swagger for Beryllium, we definitely need to do this in Boron (colindixon, 16:30:35)
    20. ACTION: colindixon to add this as a requirment for Boron (colindixon, 16:30:44)
    21. ACTION: colindixon or zxiiro to look into manually generating javadoc from autorelease instead of using maven sites in Beryllum (colindixon, 16:31:06)

  5. getting feedback from SMEs (colindixon, 16:31:34)
    1. when a tech writer comes onto a project, the assumtion is not that that they have technical knowledge of the project (colindixon, 16:32:04)
    2. instead, the assumption is taht there will be subject matter experts (SMEs) to review, give feedback, sanity check, etc. the documentation (colindixon, 16:32:32)
    3. denise says this is getting to be hard to get feedback (colindixon, 16:33:26)
    4. denise says the projects are actually pretty good about this, instead the biggest problem is getting feedback from phrobb and colindixon (colindixon, 16:34:03)
    5. denise asks if there are others who can fill that role (colindixon, 16:34:13)
    6. colindixon suggests anipbu as another person (colindixon, 16:37:21)
    7. 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 (colindixon, 16:38:19)
    8. denise says she literally goes over phrobb's house and sits in his office to get time with him, and that helps (colindixon, 16:39:43)

  6. documentation wiki page (colindixon, 16:41:33)
    1. https://wiki.opendaylight.org/view/Docucentral casey asks people to go here and see what this looks like (colindixon, 16:41:58)
    2. casey asks if we should have a centralized place for people to find documentation (colindixon, 16:42:22)
    3. 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 (colindixon, 16:43:08)
    4. 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 (colindixon, 16:44:46)
    5. colindixon says the current content we have is: getting started guide, developer guide, user guide, openstack guide (colindixon, 16:45:19)
    6. we're hoping to have API docuemntation both for JavaDoc and for YANG/RESTCONF (colindixon, 16:45:41)
    7. 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 (colindixon, 16:51:13)
    8. anipbu points out (a) we will guides guide per release and (b) we currently say contributor documentation should live on the wiki (colindixon, 16:54:24)
    9. colindixon agrees that we need some way to have multiple guides, either with subpages or with multiple entries per guide (colindixon, 16:55:57)
    10. colindixon says for now having contributor docs on the wiki where they actually are likely to be updated (colindixon, 16:57:28)
    11. 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) (colindixon, 17:00:01)

  7. project categorization (colindixon, 17:00:09)
    1. ACTION: colindixon to try to work on getting project categorization for this page https://wiki.opendaylight.org/view/Project_list (colindixon, 17:00:26)
    2. 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 (colindixon, 17:01:25)
    3. anipbu asks if we need to reconcile these categories with the TSC election categories, colindixon and casey say probably, but that shoudl be doable (colindixon, 17:01:51)


Meeting ended at 17:01:54 UTC (full logs).

Action items

  1. colindixon to ping anipbu and ask if we should start migrating to this to generate sites for all projects before Beryllum release
  2. 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
  3. colindixon to add this as a requirment for Boron
  4. colindixon or zxiiro to look into manually generating javadoc from autorelease instead of using maven sites in Beryllum
  5. 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
  6. colindixon to try to work on getting project categorization for this page https://wiki.opendaylight.org/view/Project_list


Action items, by person

  1. colindixon
    1. colindixon to ping anipbu and ask if we should start migrating to this to generate sites for all projects before Beryllum release
    2. colindixon to add this as a requirment for Boron
    3. colindixon or zxiiro to look into manually generating javadoc from autorelease instead of using maven sites in Beryllum
    4. 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
    5. colindixon to try to work on getting project categorization for this page https://wiki.opendaylight.org/view/Project_list
  2. zxiiro
    1. 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
    2. colindixon or zxiiro to look into manually generating javadoc from autorelease instead of using maven sites in Beryllum


People present (lines said)

  1. colindixon (71)
  2. odl_meetbot (4)
  3. zxiiro (2)


Generated by MeetBot 0.1.4.