@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
