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> 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> 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> 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 >>> >>
