Re: Version Beam Website Documentation

[Maximilian Michels]

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

Re: Version Beam Website Documentation

[Alex Van Boxel]

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

>>>

Re: Version Beam Website Documentation

[Kenneth Knowles]

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

Re: Version Beam Website Documentation

[Ankur Goenka]

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

Re: Version Beam Website Documentation

[Jeff Klukas]

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