Yeah, that's an interesting point.
But if you go to a project's only version of docs in git pages, they should
reflect the most recent release.
Thus, a banner makes sense.
The question ends up going back to versioning.
My current thoughts are that we should:
* Have two versions published to git pages at all times:
- the most recent "Stable"
- the work in progress "Nightly"
* We should have the Nightly generated and published via git actions upon
any changes to the source
* The Stable version should be generated and published at release time.
* We should also add a docs artifact to the release such that a version of
the docs can be downloaded for older versions
Open Question: How do you separate generation and publishing of Stable from
Nightly?
Maybe you can't and you have to generate and publish them both upon change
but the source changes need somehow only affect the Nightlies.
On Thu, May 8, 2025 at 2:12 PM Sandeep Moré <moresand...@gmail.com> wrote:
> 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/
>> >> > >
>> >> >
>> >>
>> >
>>
>
