All - I originally intended to make this a feature branch but fell into my usual git flow and once it got an approval, I merged it to master. :) It is not actually published to the git pages for the project yet - only the source has been added to the repo.
I am currently thinking that we should add a banner/note to the home page of the docs saying it is a WIP and publish them. This will facilitate easier review and finding of issues that can be easily addressed in the source files as we iterate. I'd like to get this out of WIP state for the 2.2.0 release. thoughts? --larry On Wed, Apr 23, 2025 at 10:44 AM Sandeep Moré <moresand...@gmail.com> wrote: > Thanks Larry, this looks great. > Versioning seems tricky, github offers some support for versions [1] but i > am not sure if that satisfies our use case for folks to be able to choose > older versions. > Perhaps we can add versions to features to indicate what version a feature > is supported from and make past docs downloadable? this approach appears to > be a crude solution though, I will try to think about this more and do some > research. > > Overall it looks amazing and I am excited that the code and docs will be > colocated 🤘 > > Thanks! > > [1] > https://docs.github.com/en/contributing/writing-for-github-docs/versioning-documentation > > > On Mon, Apr 21, 2025 at 12:23 PM larry mccay <lmc...@apache.org> wrote: > >> "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/ >> > > >> > >> >
