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