Hey Folks - I've long felt that the site and documentation contribution process was a bit cumbersome and have spent some time looking at alternatives.
My current thoughts are that we consider MkDocs [1] for our documentation. It takes a similar approach to what we have been doing for years by starting from markdown (.md) files that are used to generate static HTML. It then can be published to multiple places and of course manually hosted anywhere that could hot static sites. My current thinking is that we add a new module to the Knox repo called knox-site which I have done in my fork and publish the site to github pages. This is a common pattern. I have a POC published now [2] that I'd like to share for gathering ideas and thoughts. There are still some broken links, missing sequence diagrams and some organization issues that I think we will want to adjust but it looks pretty good to me. We will also want to consider how to handle versioning. We create a versioned directory structure like we have in the past, we could let it be branch based and/or we could publish a doc artifact per release that could be downloaded if needed. I'd like to try and avoid the version directory structure but we would need a good alternative. The contribution flow would be much simpler with the source md in the Knox github repo too. Let me know your thoughts and we can decide on whether a feature branch in the Apache repo is the next step. thanks! --larry 1. https://www.mkdocs.org/ 2. https://lmccay.github.io/knox/
