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