Hello Larry, I think that's a good plan, also until we have a release docs would always be WIP anyways :) given we will be pushing features then following up with docs eventually the docs would be consistent :)
On Thu, May 8, 2025 at 10:09 AM larry mccay <lmc...@apache.org> wrote: > 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/ > >> > > > >> > > >> > > >
