Re: Where to put docs on configuring specific kinds of connections? (Or restructuring the docs the way Django does)
I think the whole "Configuration" page could benefit from getting split
into separate how-to guides. Basically, every sub-heading in Configuration
becomes a different how-to guide. Since the configuration page is
attempting to do double-duty as a tutorial right now, keep the current
sequence, at least until a "Deploying a Production Airflow Environment"
tutorial is written.
I started this split (PR coming soon). I think the split document makes it
clearer where some additional guidance would be useful:
- Connections: could use some specific examples for how to created
different kinds of connections.
- Database backends: could use some specific examples on configuring a
MySQL or Postgres database backend.
* • **Tim Swast*
* • *Software Friendliness Engineer
* • *Google Cloud Developer Relations
* • *Seattle, WA, USA
On Mon, May 21, 2018 at 10:20 PM Taylor Edmiston <tedmiston@xxxxxxxxx>
> Hey Tim -
> I came to Airflow from the Django world as well and had the same thought
> that much of the work that's been put into their docs over time could be
> applied here too. In terms of documentation for large Python projects,
> perhaps they're the gold standard.
> Can you give a few examples of the specific docs you think would benefit
> from refactoring out here? I'd be happy to assist with this effort as well.
> Sent from my iPhone
> > On May 21, 2018, at 4:35 PM, 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
> > -
> > 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
> > kinds of documentation
> > <
> > 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
> > here as I've done?
> > * • **Tim Swast*
> > * • *Software Friendliness Engineer
> > * • *Google Cloud Developer Relations
> > * • *Seattle, WA, USA