+1 to site.release_latest We do have a dead link checker in the website tests. Does it not catch moved classes, etc?
On Tue, Dec 10, 2019 at 1:49 PM Pablo Estrada <[email protected]> wrote: > +1 to rely on expanding {{site.release_latest}}. > > On Tue, Dec 10, 2019 at 12:05 PM Brian Hulette <[email protected]> > 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 <[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 >>> > >>> >>
