e, but I'm
>>>>>>> confident
>>>>>>> we'll be able to work together and find a good path forward here.
>>>>>>>
>>>>>>>
>>>>>>> On Wed, Jun 5, 2024 at 3:22 PM Neil Ramaswam
o much work.
Any thoughts?
Wenchen
On Wed, Jun 5, 2024 at 1:39 AM Martin Andersson
mailto:martin.anders...@kambi.com>> wrote:
While I have no practical knowledge of how documentation is maintained in the
spark project, I must agree with Nimrod. For users on older versions, having a
p
>>>>> mentioning
>>>>>>> an improvement that a version brings motivates users to upgrade more
>>>>>>> than
>>>>>>> keeping docs improvement to "new releases to keep the community
>>>
detrimental
>>>>>>
>>>>>> I don't think that we'd do this. Again, programming guides should
>>>>>> teach fundamentals that do not change version-to-version. TypeScript
>>>>>> <https://www.typescriptlang
for
>>>>> the
>>>>> occasional caveat for a version, it is called out in the guides.
>>>>>
>>>>> I agree with Wenchen's 3 points. I don't think we need to say that
>>>>> they *have* to go to the old page, but that if
s:
>>>>>
>>>>>1. keep the old versions' programming guide unchanged. For
>>>>>example, people can still access
>>>>>https://spark.apache.org/docs/3.3.4/quick-start.html
>>>>>2. In the new versionless progra
gt;>>> keep the old versions' programming guide unchanged. For example, people
>>>>> can still access https://spark.apache.org/docs/3.3.4/quick-start.html
>>>>> In the new versionless programming guide, we mention at the beginning
>>>>> that for Spar
gt;one of 3.5), and adjust the content to mention version-specific changes
>>>>(API change, new features, etc.)
>>>>
>>>> Then we can have a versionless programming guide starting from Spark
>>>> 4.0. We can also revisit programming guides of all v
d combine
>>> them into one with version-specific notes, but that's probably too much
>>> work.
>>>
>>> Any thoughts?
>>>
>>> Wenchen
>>>
>>> On Wed, Jun 5, 2024 at 1:39 AM Martin Andersson <
>>> martin.anders...
must agree with Nimrod. For users on older
>>> versions, having a programming guide that refers to features or API methods
>>> that does not exist in that version is confusing and detrimental.
>>>
>>> Surely there must be a better way to allow updating documentation m
urely there must be a better way to allow updating documentation more
>> often?
>>
>> Best Regards,
>> Martin
>>
>> ----------
>> *From:* Nimrod Ofek
>> *Sent:* Wednesday, June 5, 2024 08:26
>> *To:* Neil Ramaswamy
>>
:* Nimrod Ofek
> *Sent:* Wednesday, June 5, 2024 08:26
> *To:* Neil Ramaswamy
> *Cc:* Praveen Gattu ; dev <
> dev@spark.apache.org>
> *Subject:* Re: [DISCUSS] Versionless Spark Programming Guide Proposal
>
>
> EXTERNAL SENDER. Do not click links or open attachments
must be a better way to allow updating documentation more often?
Best Regards,
Martin
From: Nimrod Ofek
Sent: Wednesday, June 5, 2024 08:26
To: Neil Ramaswamy
Cc: Praveen Gattu ; dev
Subject: Re: [DISCUSS] Versionless Spark Programming Guide Proposal
EXTERNAL
Hi Neil,
While you wrote you don't mean the api docs (of course), the programming
guides are also different between versions since features are being added,
configs are being added/ removed/ changed, defaults are being changed etc.
I know of "backport hell" - which is why I wrote that once a ver
Hi Nimrod,
Quick clarification—my proposal will not touch API-specific documentation
for the specific reasons you mentioned (signatures, behavior, etc.). It
just aims to make the *programming guides *versionless. Programming guides
should teach fundamentals of Spark, and the fundamentals of Spark
Hi,
While I think that the documentation needs a lot of improvement and
important details are missing - and detaching the documentation from the
main project can help iterating faster on documentation specific tasks, I
don't think we can nor should move to versionless documentation.
Documentation
+1. This helps for greater velocity in improving docs. However, we might
still need a way to provide version specific information isn't it, i.e.
what features are available in which version etc.
On Mon, Jun 3, 2024 at 3:08 PM Neil Ramaswamy wrote:
> Hi all,
>
> I've written up a proposal to migr
17 matches
Mail list logo
