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. Taylor Sent from my iPhone > On May 21, 2018, at 4:35 PM, Tim Swast <sw...@google.com.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
