+1 to rely on expanding {{site.release_latest}}.
On Tue, Dec 10, 2019 at 12:05 PM Brian Hulette <bhule...@google.com> wrote:
> I was thinking about this recently as well. I requested we add a link to
> the java API docs in a website change [1]. I searched around a bit to look
> for precedent on how to do this, but I found three different methods:
> - Links to a specific version (e.g.
> https://beam.apache.org/releases/javadoc/2.0.0/...)
> - Links to "current" (e.g.
> https://beam.apache.org/releases/javadoc/current/...)
> - Links that rely on expanding site.relase_latest (i.e.
> https://beam.apache.org/releases/javadoc/{{ site.release_latest}}/...)
>
> The first seems clearly bad if we want to always use the most recent
> version, but it does have the benefit that we don't have to worry about the
> links breaking after code changes.
>
> The latter two are effectively the same, but site.release_latest has the
> benefit that its parameterized so we _could_ generate documentation for
> other versions if we want to. It also seems to be the most prevalent. So I
> think that's the way to go. Are there any objections to updating all of our
> links to use site.release_latest?
>
> I think the only possible concern is we might break a link if we
> move/rename a class. It would be nice if there were some way to validate
> them.
>
> Brian
>
> [1] https://github.com/apache/beam/pull/10273#discussion_r354533080
>
>
> On Fri, Dec 6, 2019 at 7:20 AM Maximilian Michels <m...@apache.org> wrote:
>
>> @Kenn This is not only about breaking changes. We can also add new
>> features or settings which will then be advertised in the documentation
>> but not be available in older versions.
>>
>> Having a single source of truth is easier to maintain and better
>> discoverable via search engines. However, it forces us to use wordings
>> like "Works like this in Beam version <= X.Y, otherwise use..". The
>> pragmatic approach there is to just ignore old Beam versions. That's not
>> super user friendly, but it works.
>>
>> IMHO the amount of version-specific content in the Beam documentation
>> probably does not yet justify forking the documentation for every release.
>>
>> Cheers,
>> Max
>>
>> On 06.12.19 08:13, Alex Van Boxel wrote:
>> > It seems also be too complex for the Google Crawler as well. A lot of
>> > times I arrived on documentation on an older version of a product when
>> I
>> > search (aka Google) for something.
>> >
>> > _/
>> > _/ Alex Van Boxel
>> >
>> >
>> > On Fri, Dec 6, 2019 at 6:20 AM Kenneth Knowles <k...@apache.org
>> > <mailto:k...@apache.org>> wrote:
>> >
>> > Since we are not making breaking changes (we hope) and we try to be
>> > careful about performance regressions, I think it is OK to simply
>> > encourage users to upgrade to the latest if they expect the
>> > narrative documentation to match their version. The versioned API
>> > docs are probably enough. We might consider putting more info into
>> > the javadocs / pydocs to bridge the gap, if you have seen any issues
>> > with users hitting trouble.
>> >
>> > I am saying this for two reasons:
>> >
>> > - versioning the site is more work, and someone would need to do
>> > that work
>> > - but more than that, versioned site is more complex for users
>> >
>> > Kenn
>> >
>> > On Wed, Dec 4, 2019 at 1:48 PM Ankur Goenka <goe...@google.com
>> > <mailto:goe...@google.com>> wrote:
>> >
>> > I agree, having a single website showcase the latest beam
>> > versions and encourages users to use the latest Beam version
>> > which is very useful.
>> > Calling out version limitations are definitely makes users life
>> > easier.
>> >
>> > The usecase I have in mind is more on the lines of best
>> > practices and recommended way of doing things.
>> > One such example is the way we recommend new users to try
>> > Portable Flink. We are overhauling and simplifying the user
>> > onboarding experience. Though the old way of doing things are
>> > still supported, the easier new recommendation for onboarding
>> > will only apply from Beam 2.18.
>> > We can ofcource create sections on documentation for this
>> > usecase but it seems like a poor man's way of versioning :)
>> >
>> > You also highlighted a great usecase about LTS release. Should
>> > we simply separate out the documentations for LTS release and
>> > current version to make it easy for the users to navigate the
>> > website and reduce management overhead of updating specific
>> > sections.
>> >
>> > A few areas which might benefit from having multiple versions
>> > are compatibility matrix, Common pipeline patterns, transform
>> > catalog and runner pages.
>> >
>> >
>> > On Wed, Dec 4, 2019 at 6:19 AM Jeff Klukas <jklu...@mozilla.com
>> > <mailto:jklu...@mozilla.com>> wrote:
>> >
>> > The API reference docs (Java and Python at least) are
>> > versioned, so we have a durable reference there and it's
>> > possible to link to particular sections of API docs for
>> > particular versions.
>> >
>> > For the major bits of introductory documentation (like the
>> > Beam Programming Guide), I think it's a good thing to have
>> > only a single version, so that people referencing it are
>> > always getting the most up-to-date wording and explanations,
>> > although it may be worth adding callouts there about minimum
>> > versions anywhere we discuss newer features. We should be
>> > encouraging the community to stay reasonably current, so I
>> > think any feature that's present in the latest LTS release
>> > should be fine to assume is available to users, although
>> > perhaps we should also state that explicitly on the website.
>> >
>> > Are there particular parts of the Beam website that you have
>> > in mind that would benefit from versioning? Are there
>> > specific cases you see where the current website would be
>> > confusing for someone using a Beam SDK that's a few versions
>> > old?
>> >
>> > On Tue, Dec 3, 2019 at 6:46 PM Ankur Goenka
>> > <goe...@google.com <mailto:goe...@google.com>> wrote:
>> >
>> > Hi,
>> >
>> > We are constantly adding features to Beam which makes
>> > each new Beam version more feature rich and compelling.
>> > This also means that the old Beam released don't have
>> > the new features and might have different ways to do
>> > certain things.
>> >
>> > (I might be wrong here) - Our Beam website only publish
>> > a single version which is the latest version of
>> > documentation.
>> > This means that the users working with older SDK don't
>> > really have an easy way to lookup documentation for old
>> > versions of Beam.
>> >
>> > Proposal: Shall we consider publishing versioned Beam
>> > website to help users with old Beam version find the
>> > relevant information?
>> >
>> > Thanks,
>> > Ankur
>> >
>>
>
