git.net

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Where to put docs on configuring specific kinds of connections? (Or restructuring the docs the way Django does)


Hi Tim,

My personal opinion is to write the docs on GCP connection down at GCP Integration page <https://airflow.incubator.apache.org/integration.html#gcp-google-cloud-platform> would be an ideal fit but would like to hear others opinion as well.

+1 for creating separate How-To guides.

Regards,
Kaxil

On 21/05/2018, 21:35, "Tim Swast" <swast@xxxxxxxxxx.INVALID> wrote:

    Hey folks,
    
    I'd like to write some docs on how to create a GCP connection (and leave
    room for documenting other kinds of connections as well). Currently it
    seems like there are a couple places such a thing could fit:
    
       - https://airflow.incubator.apache.org/configuration.html#connections
       -
       https://airflow.incubator.apache.org/integration.html#gcp-google-cloud-platform
    
    There's also the concepts guide, but I definitely don't think that's the
    right place for documenting a specific task like this.
    
    There's a principle I'm used to following with the GCP docs, 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'd like to propose we split some of the existing "Configuration" topics
    into separate how-to guides. What do you think?
    
    Meta: Should I create JIRA issues for this kind of pre-discussion or start
    here as I've done?
    
    *  •  **Tim Swast*
    *  •  *Software Friendliness Engineer
    *  •  *Google Cloud Developer Relations
    *  •  *Seattle, WA, USA
    
    
    



Kaxil Naik 

Data Reply
2nd Floor, Nova South
160 Victoria Street, Westminster
London SW1E 5LB - UK 
phone: +44 (0)20 7730 6000
k.naik@xxxxxxxxx
www.reply.com