#opendaylight-meeting: TWS

Meeting started by Madhu at 17:04:32 UTC (full logs).

Meeting summary

  1. Documentation process for Helium (colindixon, 17:05:56)
    1. regXboi taking the lead on documentation process (Madhu, 17:06:05)
    2. https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Docs_and_Structure link for docs for Helium (tbachman, 17:06:25)
    3. https://wiki.opendaylight.org/view/CrossProject:Documentation_Group Documentation group page (Madhu, 17:06:50)
    4. documentation has its own repo and every Helium participating project needs to update their documentation on this project (Madhu, 17:07:13)
    5. https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:How_To the how to page regXboi is going through (colindixon, 17:08:37)
    6. once you have documentation you want to add, use the decision matrix on that wiki page to determine where that documentation goes (tbachman, 17:09:03)
    7. the docs project is for documentation that is angled to people both in the ODL community and outside the ODL community (colindixon, 17:09:14)
    8. there is a giant flow chart that shows how to decide what kind of documentation you need to create (colindixon, 17:09:43)
    9. there is a docs channel: #opendaylight-docs where you can go ask for help (colindixon, 17:10:12)
    10. https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:Tools tools for documentation (tbachman, 17:11:07)
    11. you can build documentation in linux, but not in windows (tbachman, 17:11:20)
    12. you should be able to find your project as a .adoc projet somewhere in the docs project (colindixon, 17:14:04)
    13. it may be in multiple places, this should be your own chapter (or section or file) (colindixon, 17:14:31)
    14. you may need to add it in other places: regXboi shows that there is a controller.adoc in the developers-guide, operations-guide and user-guide (should probably also be in the installation guide) (colindixon, 17:16:23)
    15. raghu67 asks how we plan to deliver the docs when the distribution is downloaded? Are they delivered separately (tbachman, 17:16:33)
    16. regXboi says there will be site deploy job to a maven site to make them available online (tbachman, 17:17:08)
    17. these .adoc files are linked into the “books” which are called bk-*.adoc, e.g., bk-user-guide.adoc (you can find them with something like “find . -name bk*.adoc”) (colindixon, 17:18:19)
    18. regXboi says that for Helium (unlike in Hydrogen), docs will be forked onto a stable helium brnach that will (forever and always) have helium docs while master will then move on to Lithium and so on (colindixon, 17:19:26)
    19. networkstatic asks if any of the projects had already done the work and could be used as a reference (tbachman, 17:20:04)
    20. colindixon says that the l2switch project has documentation that looks good, but that may be on a private repo (tbachman, 17:20:26)
    21. regXboi says that the “door is open” for projects to start submitting their documentation, so they can be used as a reference (tbachman, 17:21:11)
    22. https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:How_To wiki page explaining to projects how to generate and deploy documentation (tbachman, 17:22:06)
    23. regXboi recommends going through step 5 lots of times, as there are lots of interesting side-effects (i.e. review what it generates, and make sure it looks like you want it to) (tbachman, 17:23:05)
    24. regXboi notes that step 5 “build/review/edit test documentation by following these steps” is importa, for example you *must* leave a blank line at the end of every chapter of things will go wonky (colindixon, 17:23:08)

  2. demo (colindixon, 17:23:45)
    1. regXboi edits the controller.adoc file in the developer’s guide to add a few words (colindixon, 17:24:34)
    2. regXboi notes that if you do “mvn install” it will likely not re-generate the pdfs, make sure to have clean in there, e.g., “mvn clean install" (colindixon, 17:26:00)
    3. once you’ve made all your changes, push your changes to gerrit (tbachman, 17:28:01)
    4. the documentation committers may come back and talk to you about your commit (tbachman, 17:28:24)
    5. shows opening target/docbkx/webhelp/bk-developers-guide/bk-developers-guide-20140915.pdf (now has the controller text in it) (colindixon, 17:28:53)

  3. high-level steps (colindixon, 17:30:06)
    1. 1.) go to the documentaiton how to page and go through the flow chart (colindixon, 17:30:50)
    2. https://wiki.opendaylight.org/view/CrossProject:Documentation_Group:How_To the documentation how to page (colindixon, 17:31:07)
    3. 2.) the flow chart will tell you what kind of docs you should create (colindixon, 17:31:59)
    4. 3.) each kind of docs, e.g., user guide, developer guide, has a folder in the docs git repo (colindixon, 17:32:25)
    5. 4.) in each of those folders there should be a .adoc file for your project, if not, reach out and/or just create it for yourself (colindixon, 17:33:09)
    6. 5.) add your stuff and test building it to make sure it looks right, then push it for review just like any other code (colindixon, 17:33:35)

  4. more questions (colindixon, 17:38:58)
    1. networkstatic asks if we should focus on the wiki or asciidoc (colindixon, 17:39:06)
    2. regXboi and colindixon say that they think focusing on the asciidoc makes more sense, but they aren’t part of the docs project (colindixon, 17:40:12)
    3. colindixon in particular notes that the effort might be less: to get the wiki docs up you need to find the good and elminate the bad, to get the asciidocs working just involves finding the good and copying it into the asciidoc (colindixon, 17:40:53)
    4. networkstatic asks if the set of docs that gets in that losk good could be sent out to a braoder audience as a good example (colindixon, 17:45:01)

  5. hardcore pleading for people to test their features in RCs (colindixon, 17:45:21)
    1. colindixon urges projects to test and use their code as their users would, in order to make sure that everything is working (tbachman, 17:47:02)
    2. colindixon gets down on his hands an knees and pleads for for people to actually download RCs either the weeklies or the nightlies and test it (colindixon, 17:47:31)
    3. colindixon says not just running mvn clean install, but actually bring the distribution up, bring up the features you want to test (and the ones you think people will want to run with your stuff) and then make sure what you want your users to do works (colindixon, 17:48:13)
    4. do this *at least* once a week, and preferably more often (colindixon, 17:48:51)

  6. remaining things (colindixon, 17:50:00)
    1. what we *need* need to do is test, Test, TEST and doc, Doc, DOC now (colindixon, 17:50:17)
    2. CASP3R says please, reach out to integration if you need help with tests, etc. (colindixon, 17:50:46)


Meeting ended at 17:51:56 UTC (full logs).

Action items

  1. (none)


People present (lines said)

  1. colindixon (39)
  2. tbachman (27)
  3. Madhu (9)
  4. odl_meetbot (7)
  5. phrobb (4)
  6. networkstatic (1)


Generated by MeetBot 0.1.4.