#opendaylight-docs: docs

Meeting started by colindixon at 19:01:28 UTC (full logs).

Meeting summary

  1. agenda bashing (colindixon, 19:01:47)
    1. https://git.opendaylight.org/gerrit/#/c/38847/ (colindixon, 19:07:05)
    2. last time we covered what a migration to read the docs might look like: https://meetings.opendaylight.org/opendaylight-docs/2016/docs/opendaylight-docs-docs.2016-05-10-19.01.html (colindixon, 19:08:17)
    3. https://lists.opendaylight.org/pipermail/documentation/2016-May/000700.html colindixon asked how to integrate javadoc, REST API docs, etc. with read the docs (colindixon, 19:09:06)
    4. the answer seems to be we're not any worse than the last way, in both directions it accepts static HTML, so we ought to be able to do that (colindixon, 19:10:05)
    5. https://opendaylight.readthedocs.io/en/latest/ (zxiiro, 19:10:43)

  2. progress on read the docs (colindixon, 19:11:56)
    1. https://opendaylight.readthedocs.io/en/latest/ you can now see the infrastructure guide which has releng/builder docs even though they're hosted in the releng/builder repo (colindixon, 19:12:43)
    2. anipbu says we should talk about what terms to use, handbook vs. guide vs. manual (colindixon, 19:13:20)
    3. zxiiro notes that we only use handbook at the root of the new readthedocs page, colindixon notes that manual is only used in the file system structure (colindixon, 19:14:19)
    4. it appears as though we call everything a guide except that all the guides together are called the handbook (colindixon, 19:14:57)

  3. introducing this work to the broader community (colindixon, 19:15:40)
    1. on the TSC call last week, some people seemed somewhat upset about moving away from asciidocs (colindixon, 19:16:05)
    2. https://git.opendaylight.org/gerrit/#/q/project:docs+status:open,25 (anipbu, 19:16:10)
    3. we need to explain how and when this will happen and how it will be done to avoid people (colindixon, 19:17:39)

  4. preparing for Boron docs reviews (colindixon, 19:17:54)
    1. ACTION: colindixon to contacat a docs review committee including abhijitkumbhare, ChrisPriceAB, CaseyODL, dfarrell07, and anipbu are the first bit (colindixon, 19:19:50)
    2. ACTION: anipbu to set up a documentation review spreadsheet (colindixon, 19:21:28)
    3. https://docs.google.com/spreadsheets/d/1PYxjiSYEks44uJByVO1P44rnI5xTJRulpKyrSsDQF9g/edit?pli=1#gid=613128231 this is the one I used for Lithium (colindixon, 19:21:37)
    4. https://docs.google.com/spreadsheets/d/1d-Qay-9IAy5OIECPGHj-Xtw24ey6UEzIEk9RSJuD5uo/edit#gid=22029863 anipbu documentation tracking sheet (colindixon, 19:24:35)

  5. back to bringing sphinx/readthedocs/rst to the community (colindixon, 19:25:53)
    1. colindixon notes that we need to do a TWS to introduce people to this toolchain at some point (colindixon, 19:27:33)
    2. zxiiro says getting projects to convert would be good before then (colindixon, 19:27:40)
    3. maybe getting the infrastructure folks to do that (colindixon, 19:27:52)
    4. colindixon asks about having a verify jobs for sphinx, we are getting close to having one for docs: https://git.opendaylight.org/gerrit/#/c/38951/ (colindixon, 19:30:26)
    5. after that, we either need to use that for all docs and trigger it on all project changes on docs in those projects when they build (colindixon, 19:31:52)
    6. ACTION: colindixon to look at converting TTP docs to RST and sphinx, zxiiro offers to help anipbu with USC (colindixon, 19:32:38)
    7. anipbu asks about a guide for migration, zxiiro says there isn't one yet, and there isn't a patch that coverts a document in place (colindixon, 19:34:09)
    8. colindixon says it sounds a week from this Monday is probably as early as we could imagine having this in the shape that we want (colindixon, 19:35:00)

  6. boron plans (colindixon, 19:36:05)
    1. anipbu asks if we want everyone to move all projects to read the docs in Boron, colindixon says he'd love to, but he doesn't see how we could do that in boron unless the docs team has to figure out hwo to move all projects (colindixon, 19:38:24)
    2. https://git.opendaylight.org/gerrit/gitweb?p=docs.git;a=tree;f=manuals/getting-started-guide/src/main/asciidoc/ovsdb; (anipbu, 19:40:13)
    3. colindixon says that in his mind, you probably want to completely convert or not convert things on a guide-by-guide basis (colindixon, 19:42:24)
    4. http://hyperpolyglot.org/lightweight-markup <-- Colin links in tool for conversion (anipbu, 19:43:05)
    5. e.g., we might convert the getting started guide and (maybe) the openstack guide (colindixon, 19:45:09)
    6. ACTION: colindixon to work with projects in the getting started guide to migrate to RST and be in the new getting started guide (colindixon, 19:46:11)
    7. ACTION: colindixon to reach out to the projects in the openstack guide to see if they'd be willing to migrate to readthedocs (colindixon, 19:48:45)
    8. https://github.com/opendaylight/docs/blob/master/docs/getting-started-guide/index.rst#getting-started-guide (colindixon, 19:48:46)
    9. colindixon asks if others think we might be able to migrate *everything* in boron, anipbu says that sounds like it will be harder to do do things beyond the getting started guide and openstack guide (colindixon, 19:51:16)
    10. ACTION: anipbu to work on auto-conversion from AsciiDoc to rst (colindixon, 19:52:37)
    11. https://github.com/aria2/aria2/commit/003aaf4a09c998572e50043885be25f3b4c20bf7 one example conversion (colindixon, 19:53:14)
    12. http://hyperpolyglot.org/lightweight-markup comparison of different lightweight markup languages (colindixon, 19:53:37)
    13. http://pandoc.org/demos.html (colindixon, 19:54:29)
    14. http://pandoc.org/demos.html claims to support both asciidoc and rst and conversion (colindixon, 19:55:12)
    15. ACTION: colindixon to create some documentation around the conversion process with a secotion about issues and workarounds (colindixon, 19:59:21)


Meeting ended at 20:01:28 UTC (full logs).

Action items

  1. colindixon to contacat a docs review committee including abhijitkumbhare, ChrisPriceAB, CaseyODL, dfarrell07, and anipbu are the first bit
  2. anipbu to set up a documentation review spreadsheet
  3. colindixon to look at converting TTP docs to RST and sphinx, zxiiro offers to help anipbu with USC
  4. colindixon to work with projects in the getting started guide to migrate to RST and be in the new getting started guide
  5. colindixon to reach out to the projects in the openstack guide to see if they'd be willing to migrate to readthedocs
  6. anipbu to work on auto-conversion from AsciiDoc to rst
  7. colindixon to create some documentation around the conversion process with a secotion about issues and workarounds


Action items, by person

  1. anipbu
    1. colindixon to contacat a docs review committee including abhijitkumbhare, ChrisPriceAB, CaseyODL, dfarrell07, and anipbu are the first bit
    2. anipbu to set up a documentation review spreadsheet
    3. colindixon to look at converting TTP docs to RST and sphinx, zxiiro offers to help anipbu with USC
    4. anipbu to work on auto-conversion from AsciiDoc to rst
  2. colindixon
    1. colindixon to contacat a docs review committee including abhijitkumbhare, ChrisPriceAB, CaseyODL, dfarrell07, and anipbu are the first bit
    2. colindixon to look at converting TTP docs to RST and sphinx, zxiiro offers to help anipbu with USC
    3. colindixon to work with projects in the getting started guide to migrate to RST and be in the new getting started guide
    4. colindixon to reach out to the projects in the openstack guide to see if they'd be willing to migrate to readthedocs
    5. colindixon to create some documentation around the conversion process with a secotion about issues and workarounds
  3. zxiiro
    1. colindixon to look at converting TTP docs to RST and sphinx, zxiiro offers to help anipbu with USC


People present (lines said)

  1. colindixon (43)
  2. anipbu (5)
  3. odl_meetbot (3)
  4. zxiiro (3)


Generated by MeetBot 0.1.4.