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/ > > > > > >
