metron-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Miklavcic <>
Subject [DISCUSS] Metron documentation improvements
Date Thu, 20 Dec 2018 19:47:00 GMT
We recently had our site-book doc generation break due to our not including
it in the Travis build. The fix for a broken build seems simple enough -
add it to our build process and assuming it doesn't cause build timeout
issues, we should be good to go.

Beyond that, there are additional issues with the existing process. We have
a step in our PR review for validating that the docs are rendering
properly. I know I've gone back and corrected issues with broken images or
incorrectly rendering pages at least a few times now. On one hand, we might
say this is simply a matter of being better about validating documentation
during the review process. That may be true, but rather than fight upstream
like a salmon, I would prefer to simplify things, automate what we can, and
use technology to work with us. Based on this conversation on METRON-1950 -
I'd like to open up a general convo about improvements to our documentation

*Current Issues:*

   1. Duplicated effort - have to check pages render in Github and the
   Doxia-generated site-book
   2. Inconsistent model - what works for Github markdown may not work for
   Doxia, and vice versa
   3. Github is part of our workflow and easy to check, Doxia requires an
   extra separate step - suffers unintentional bugs due to #2.
   4. Images have to be manually added to the site rendering code for
   copying to the "images" folder, and explicit src ref replacements have to
   be included for all affected pages/links as well.
   5. Page links and images are not validated - this currently requires
   manual review and intervention during PR review and whenever we create a
   new Metron release.
   6. Failed site-book build is not validated. Broken build does not fail

*Options and Solutions:*

   1. Otto has already brought up using Ascii doc as one option for solving
   a number of these issues.
   2. For issue #5, we can write a scraper that validates links or use
   tooling like Cypress for this.
   3. For issue #6, we can add site-book building to our Travis runs. It's
   pretty quick to generate and will catch the more egregious rendering bugs.
   I plan to look at this presently.


  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message