[GitHub] [airflow] potiuk commented on pull request #28300: Add Public Interface description to Airflow documentation

[GitBox]

potiuk commented on PR #28300:
URL: https://github.com/apache/airflow/pull/28300#issuecomment-1351030386

   Hey @BasPH  - explained reasoning why I addded those a bit longer 
explanation and context. 
   
   I hope this is good for you as well.
   
   One of the cases which I want to address is to be able to explain people 
that if they do rely on some of those things being explained as "public 
interface" , even if they do, whenever they complain or raise questions about 
that I want to simply send them there - "Please read the docs, it's all 
explained there and you likely missed it". 
   
   That saves enormous mental effort and time in disputes when you engage in 
such discussions (which are often) "but you did not explain it, I had the right 
to think it works this way".
   
   Also just to stress a bit that my "thinking" is not theorethical. It is very 
much based on practice of interacting with our users A LOT. I would encourage 
everyone to engage more in discussions we have in our community - or at least 
review them and follow. So far not many of us, maintainers are engaged, I think 
I understand quite well - and likely bettter than others - what our users are 
struggling with as well what is helpful for people. 
   
   I am not sure if you realize, but over the last 6 months or so the status of 
Github Discussions of ours looks like that (I have - very consistently 11/15 
"most helpful" answers last 30 days while the next person never had more than 
1-2:
   
   <img width="378" alt="Screenshot 2022-12-14 at 12 12 02" 
src="https://user-images.githubusercontent.com/595491/207580648-449f0380-d37b-46d6-aeac-3996da820d5d.png";>
   
   And the raise in a number of discussions looks like that - so this is an 
extremely important medium where our users look for help:
   
   <img width="469" alt="Screenshot 2022-12-14 at 12 16 02" 
src="https://user-images.githubusercontent.com/595491/207581299-04ced62f-b4ae-47ed-aa9b-c11d8ee727ea.png";>
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscr...@airflow.apache.org

For queries about this service, please contact Infrastructure at:
us...@infra.apache.org