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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 >>>> >>>
