You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@knox.apache.org by larry mccay <lm...@apache.org> on 2025/04/21 15:29:53 UTC
[DISCUSS] Knox Documentation Framework, Hosting and Contribution
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/
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by Phil Zampino <pz...@apache.org>.
Got it. Docs don't always get the attention they deserve; This will be a
nice improvement for Knox.
On Mon, Apr 21, 2025 at 12:23 PM larry mccay <lm...@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 <pz...@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 <lm...@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/
> > >
> >
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by Phil Zampino <pz...@apache.org>.
Got it. Docs don't always get the attention they deserve; This will be a
nice improvement for Knox.
On Mon, Apr 21, 2025 at 12:23 PM larry mccay <lm...@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 <pz...@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 <lm...@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/
> > >
> >
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by larry mccay <la...@gmail.com>.
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é <mo...@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 <lm...@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é <mo...@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 <lm...@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 <pz...@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 <lm...@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/
>> >> > >
>> >> >
>> >>
>> >
>>
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by larry mccay <la...@gmail.com>.
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é <mo...@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 <lm...@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é <mo...@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 <lm...@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 <pz...@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 <lm...@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/
>> >> > >
>> >> >
>> >>
>> >
>>
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by Sandeep Moré <mo...@gmail.com>.
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 <lm...@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é <mo...@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 <lm...@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 <pz...@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 <lm...@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/
> >> > >
> >> >
> >>
> >
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by Sandeep Moré <mo...@gmail.com>.
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 <lm...@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é <mo...@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 <lm...@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 <pz...@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 <lm...@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/
> >> > >
> >> >
> >>
> >
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by larry mccay <lm...@apache.org>.
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é <mo...@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 <lm...@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 <pz...@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 <lm...@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/
>> > >
>> >
>>
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by larry mccay <lm...@apache.org>.
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é <mo...@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 <lm...@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 <pz...@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 <lm...@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/
>> > >
>> >
>>
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by Sandeep Moré <mo...@gmail.com>.
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 <lm...@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 <pz...@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 <lm...@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/
> > >
> >
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by Sandeep Moré <mo...@gmail.com>.
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 <lm...@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 <pz...@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 <lm...@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/
> > >
> >
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by larry mccay <lm...@apache.org>.
"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 <pz...@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 <lm...@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/
> >
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by larry mccay <lm...@apache.org>.
"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 <pz...@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 <lm...@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/
> >
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by Phil Zampino <pz...@apache.org>.
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 <lm...@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/
>
Re: [DISCUSS] Knox Documentation Framework, Hosting and Contribution
Posted by Phil Zampino <pz...@apache.org>.
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 <lm...@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/
>