[jira] [Comment Edited] (AIRFLOW-2509) Separate Configuration page into separate how-to guides

["Kaxil Naik (JIRA)" <ji...@apache.org>]

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

Kaxil Naik edited comment on AIRFLOW-2509 at 5/23/18 9:45 AM:
--------------------------------------------------------------

[~tswast] Can you update the documentation [here|http://airflow.readthedocs.io/en/latest/howto/create-connection.html] to say that you can also create connections using the Airflow Web UI which is much easy and intuitive as compared to environment variables method and also point to the specific link of creating connection (see [here|http://airflow.readthedocs.io/en/latest/concepts.html#connections] ) instead of linking it to the concepts section?

Or instead of 2 separate pages i.e 1) *[Securing connections|http://airflow.readthedocs.io/en/latest/howto/secure-connections.html]*, and 2) *[Creating connections|http://airflow.readthedocs.io/en/latest/howto/create-connection.html]*: I think a single page Creating and Securing connections would make more sense.

What do you think about it [~tswast]?


was (Author: kaxilnaik):
[~tswast] Can you update the documentation here to say that you can also create connections using the Airflow Web UI which is much easy and intuitive as compared to environment variables method and also point to the specific link of creating connection (see here ) instead of linking it to the concepts section?

Or instead of 2 separate pages i.e 1) Securing connections, and 2) Creating connections: I think a single page Creating and Securing connections would make more sense.

What do you think about it [~tswast]?

> Separate Configuration page into separate how-to guides
> -------------------------------------------------------
>
>                 Key: AIRFLOW-2509
>                 URL: https://issues.apache.org/jira/browse/AIRFLOW-2509
>             Project: Apache Airflow
>          Issue Type: Improvement
>          Components: Documentation
>            Reporter: Tim Swast
>            Assignee: Tim Swast
>            Priority: Critical
>             Fix For: 2.0.0
>
>
> The existing "Configuration" page is attempting to be both a tutorial (teaching the basics of Airflow configuration & a minimal production deployment) as well as how-tos for specific tasks.
>  
> I propose we separate Configuration into separate how-to guides, keeping the current sequence so that it can still maintain the tutorial properties (at least until a "Deploying a Production Airflow Environment" tutorial is written).
>  
> There's a principle that the [distinct kinds of documentation|http://www.writethedocs.org/videos/eu/2017/the-four-kinds-of-documentation-and-why-you-need-to-understand-what-they-are-daniele-procida/] should be organized separately. The Django project does this [https://docs.djangoproject.com/en/2.0/] by splitting into
>  
>  * Tutorials
>  * Topic guides (what Airflow calls Concepts)
>  * Reference guides
>  * How-to guides
> I think the same could apply well here. (This issue covers only How-to for Configuration. More work would be required to separate other docs into proper document types.)



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)