"Are you proposing that we maintain multiple versions of the docs available online, or would "older" releases only be available by download?"
I'm not proposing anything quite yet. If we have a versioned directory structure, I would expect that to be reflected in the published docs such that they would be available online. The release artifact would be something that made the previous versions available through the archived releases at Apache. Otherwise, I have to dig into the options of Github Pages for versioning and see what it would look like if it was branch based or versioned directories. On Mon, Apr 21, 2025 at 11:59 AM Phil Zampino <pzamp...@apache.org> wrote: > Larry - > Thank you for raising this proposal. I agree that the documentation > contribution process has been unnecessarily cumbersome, and that the > resulting HTML feels antiquated. Making it easier to contribute may lead to > more frequent improvements of the content from the community, and with less > room for errors. > > I like the layout and general appearance of the POC you've published, and I > especially appreciate the search functionality. > > Concerning versioning, the branching approach feels the most natural, even > more so if the docs source will be co-located with the code (which I think > it should be). > Branching also feels safer than copying files/directories and making sure > they all get committed, and PRs are easier to review than patch files IMO. > > Are you proposing that we maintain multiple versions of the docs available > online, or would "older" releases only be available by download? > > Thanks again, > Phil > > On Mon, Apr 21, 2025 at 11:30 AM larry mccay <lmc...@apache.org> wrote: > > > 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/ > > >
