[jira] [Commented] (AIRFLOW-6556) Improving unclear and incomplete documentation
[ https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17016155#comment-17016155 ] Jacob Ward commented on AIRFLOW-6556: - Here's a list of issues myself and my team have noticed. I'll add more as I notice them. * [Kubernetes|https://airflow.apache.org/docs/stable/kubernetes.html]: ** An explanation of how the KubernetesExecutor (KE) and KubernetesPodOperator (KPO) work. ** An explanation of the difference between the KE & KPO (I see this question and confusion arise a lot in slack). ** An explanation of exactly what the [kubernetes] config options are used for with the KE (something that I have only just started to understand is that these config options mostly apply to the workers, since the scheduler does not _have_ to run inside the cluster with KE). ** (Minor) The KPO hyperlink on the Kubernetes doc page sends you to the KE page. Also the links on this page send you to readthedocs.io * Some information [(possibly here)|https://airflow.apache.org/docs/stable/concepts.html?highlight=trigger%20rule#dag-assignment] about how assigning operators to dags after creation means the default_args aren't applied. * In general I think the Concepts/Core Ideas section has a lot of interesting and useful information, but since it is one long page it makes it harder to find the information you need. I think this would be better split into several pages with more information and examples for each concept. * Some information on best practice, how to avoid common pitfalls, etc. * [LocalExecutor is missing|https://airflow.apache.org/docs/stable/executor/index.html] and some general information on the architecture and how these Executors are supposed to work would be useful. I often see new users getting confused by what the Executor really is, and get this and operators mixed up at times. * [Security|https://airflow.apache.org/docs/stable/security.html#viewer] - What all the permissions are, and what does each one actually mean? E.g. 'can_show' is not descriptive enough to know exactly what it means. > Improving unclear and incomplete documentation > -- > > Key: AIRFLOW-6556 > URL: https://issues.apache.org/jira/browse/AIRFLOW-6556 > Project: Apache Airflow > Issue Type: Improvement > Components: documentation >Affects Versions: master >Reporter: Jacob Ward >Assignee: Jarek Potiuk >Priority: Trivial > > To help improve documentation it was discussed in the mailing list that users > of Airflow should have somewhere to report missing, incomplete or unclear > documentation. Any users who find this should comment on this ticket. -- This message was sent by Atlassian Jira (v8.3.4#803005)
[jira] [Commented] (AIRFLOW-6556) Improving unclear and incomplete documentation
[ https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17016323#comment-17016323 ] Jarek Potiuk commented on AIRFLOW-6556: --- Thanks [~jward]! Some of these we already have on our list. It's good to have the list here. I will discuss it with others involved in the docs and we'll see what we can do. I hope, once we have some drafts we can count on you and your team to review and give feedback on what we propose. > Improving unclear and incomplete documentation > -- > > Key: AIRFLOW-6556 > URL: https://issues.apache.org/jira/browse/AIRFLOW-6556 > Project: Apache Airflow > Issue Type: Improvement > Components: documentation >Affects Versions: master >Reporter: Jacob Ward >Assignee: Jarek Potiuk >Priority: Trivial > > To help improve documentation it was discussed in the mailing list that users > of Airflow should have somewhere to report missing, incomplete or unclear > documentation. Any users who find this should comment on this ticket. -- This message was sent by Atlassian Jira (v8.3.4#803005)
[jira] [Commented] (AIRFLOW-6556) Improving unclear and incomplete documentation
[ https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17016746#comment-17016746 ] Jacob Ward commented on AIRFLOW-6556: - Absolutely! > Improving unclear and incomplete documentation > -- > > Key: AIRFLOW-6556 > URL: https://issues.apache.org/jira/browse/AIRFLOW-6556 > Project: Apache Airflow > Issue Type: Improvement > Components: documentation >Affects Versions: master >Reporter: Jacob Ward >Assignee: Jarek Potiuk >Priority: Trivial > > To help improve documentation it was discussed in the mailing list that users > of Airflow should have somewhere to report missing, incomplete or unclear > documentation. Any users who find this should comment on this ticket. -- This message was sent by Atlassian Jira (v8.3.4#803005)
[jira] [Commented] (AIRFLOW-6556) Improving unclear and incomplete documentation
[ https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17016788#comment-17016788 ] Jarek Potiuk commented on AIRFLOW-6556: --- Cool. I don't promise anything super-fast, but I will look for opportunities how to engage more people. Having this issue here provided by users and User's support for review is crucial to get people involved! > Improving unclear and incomplete documentation > -- > > Key: AIRFLOW-6556 > URL: https://issues.apache.org/jira/browse/AIRFLOW-6556 > Project: Apache Airflow > Issue Type: Improvement > Components: documentation >Affects Versions: master >Reporter: Jacob Ward >Assignee: Jarek Potiuk >Priority: Trivial > > To help improve documentation it was discussed in the mailing list that users > of Airflow should have somewhere to report missing, incomplete or unclear > documentation. Any users who find this should comment on this ticket. -- This message was sent by Atlassian Jira (v8.3.4#803005)
[jira] [Commented] (AIRFLOW-6556) Improving unclear and incomplete documentation
[ https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17016838#comment-17016838 ] Kamil Bregula commented on AIRFLOW-6556: I would be happy if they were added to the documentation: *Webserver*: * General information e.g. why do we need him? * How to configure webserver? We have a lot of options that are not described. * Various information is also spread over several pages and I think it is worth collecting them in a commonplace *Scheduler*: * General information e.g. why do we need him? * How to configure scheduler? We have a lot of options that are not described. A lot of information is on the "Concept" page and should be on a separate subpage. *Logging*: We have documentation about writing, but we don't have documentation on how to use and how to configure reading. We don't have descriptions on how to use it. *Security*: This page needs to be split because RBAC is only part of the UI interface and is confused with full isolation. *SMTP*: The configuration of the email configuration description should be on a separate page. This should not be on the "Concept" page. This is very confusing and introduces unnecessary information for end-users - not administrators. *CeleryExecutor*: Documentation describing the configuration is in the initial phase. I think it's worth expanding. *Systemd/upstart:* Page "Running Airflow with systemd" and page "Running Airflow with upstart" should be combined and contain a common introduction e.g. the goals and differences between the two solutions. *Using the Test Mode Configuration* I think this page should be combined with the "Setting Configuration Options" page. *Database*: I think there is a lack of documentation that allows you to choose the right database and facilitates its configuration and use. The documentation only describes the `airflow db init` option. This should also include a description of the other `db` commands. *Telemetry*: I would be happy if the general information about telemetry has been added, which would contain references to following section: * Logs * Metrics - Statsd * tracking error - Sentry * Tracking User Activity(Google Analytics etc) * Graph descriptions that are generated in Airflow UI. This should also describe the purposes and ways of using this data. The statsd description should also show a simple description of use, e.g. using Stackdriver Metrics or Graphana. > Improving unclear and incomplete documentation > -- > > Key: AIRFLOW-6556 > URL: https://issues.apache.org/jira/browse/AIRFLOW-6556 > Project: Apache Airflow > Issue Type: Improvement > Components: documentation >Affects Versions: master >Reporter: Jacob Ward >Assignee: Jarek Potiuk >Priority: Trivial > > To help improve documentation it was discussed in the mailing list that users > of Airflow should have somewhere to report missing, incomplete or unclear > documentation. Any users who find this should comment on this ticket. -- This message was sent by Atlassian Jira (v8.3.4#803005)
[jira] [Commented] (AIRFLOW-6556) Improving unclear and incomplete documentation
[ https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17017488#comment-17017488 ] Anton Zayniev commented on AIRFLOW-6556: *Mailing list:* I think we need some onboarding for ppl not familiar with that kind of interaction: * devlist etiquette * hint to ease lists usage (like mail filters/rules, pony mail, etc.) * why do devlist preferred over slack, gitter, etc. > Improving unclear and incomplete documentation > -- > > Key: AIRFLOW-6556 > URL: https://issues.apache.org/jira/browse/AIRFLOW-6556 > Project: Apache Airflow > Issue Type: Improvement > Components: documentation >Affects Versions: master >Reporter: Jacob Ward >Assignee: Jarek Potiuk >Priority: Trivial > > To help improve documentation it was discussed in the mailing list that users > of Airflow should have somewhere to report missing, incomplete or unclear > documentation. Any users who find this should comment on this ticket. -- This message was sent by Atlassian Jira (v8.3.4#803005)
[jira] [Commented] (AIRFLOW-6556) Improving unclear and incomplete documentation
[ https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17017504#comment-17017504 ] Jarek Potiuk commented on AIRFLOW-6556: --- [~uncletoxa] (y) > Improving unclear and incomplete documentation > -- > > Key: AIRFLOW-6556 > URL: https://issues.apache.org/jira/browse/AIRFLOW-6556 > Project: Apache Airflow > Issue Type: Improvement > Components: documentation >Affects Versions: master >Reporter: Jacob Ward >Assignee: Jarek Potiuk >Priority: Trivial > > To help improve documentation it was discussed in the mailing list that users > of Airflow should have somewhere to report missing, incomplete or unclear > documentation. Any users who find this should comment on this ticket. -- This message was sent by Atlassian Jira (v8.3.4#803005)
[jira] [Commented] (AIRFLOW-6556) Improving unclear and incomplete documentation
[
https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17017862#comment-17017862
]
Kamil Bregula commented on AIRFLOW-6556:
*How to set the log level for the current console?*
It facilitates debugging e.g.
[https://apache-airflow.slack.com/archives/CCVDRN0F9/p1579254738000300?thread_ts=1579198094.011300&cid=CCVDRN0F9]
If you set logging level to DEBUG, more information appears in the console.
This makes it easy to find the root of problem.
On 1.10+
{{AIRFLOW__CORE__LOGGING_LEVEL=DEBUG airflow tasks test examplebash task
2019-01-01}}
On 1.10+
{{AIRFLOW__LOGGING__LOGGING_LEVEL=DEBUG airflow tasks test examplebash task
2019-01-01}}
> Improving unclear and incomplete documentation
> --
>
> Key: AIRFLOW-6556
> URL: https://issues.apache.org/jira/browse/AIRFLOW-6556
> Project: Apache Airflow
> Issue Type: Improvement
> Components: documentation
>Affects Versions: master
>Reporter: Jacob Ward
>Assignee: Jarek Potiuk
>Priority: Trivial
>
> To help improve documentation it was discussed in the mailing list that users
> of Airflow should have somewhere to report missing, incomplete or unclear
> documentation. Any users who find this should comment on this ticket.
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
