[jira] [Comment Edited] (AIRFLOW-6556) Improving unclear and incomplete documentation

["Jacob Ward (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/AIRFLOW-6556?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17016155#comment-17016155 ] 

Jacob Ward edited comment on AIRFLOW-6556 at 1/15/20 5:09 PM:
--------------------------------------------------------------

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.
 * It may be covered by Kaxil's updates to the config documentation, but a page on how new dags are picked up, parsed and stored, and what the DagBag is and it interacts with/or is interacted with by the scheduler/webserver/db.


was (Author: jward):
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)