git.net

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

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


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


( ! ) Warning: include(msgfooter.php): failed to open stream: No such file or directory in /var/www/git/apache-airflow-development/msg03425.html on line 102
Call Stack
#TimeMemoryFunctionLocation
10.0008364760{main}( ).../msg03425.html:0

( ! ) Warning: include(): Failed opening 'msgfooter.php' for inclusion (include_path='.:/var/www/git') in /var/www/git/apache-airflow-development/msg03425.html on line 102
Call Stack
#TimeMemoryFunctionLocation
10.0008364760{main}( ).../msg03425.html:0