Small changes on "DAGs and Tasks documentation" (apache#14853)

airflow/example_dags/tutorial.py

@@ -89,18 +89,21 @@
     # [END basic_task]
 
     # [START documentation]
-    dag.doc_md = __doc__
-
     t1.doc_md = dedent(
         """\
     #### Task Documentation
     You can document your task using the attributes `doc_md` (markdown),
     `doc` (plain text), `doc_rst`, `doc_json`, `doc_yaml` which gets
     rendered in the UI's Task Instance Details page.
-
     ![img](http://montcs.bloomu.edu/~bobmon/Semesters/2012-01/491/import%20soul.png)
+
     """
     )
+
+    dag.doc_md = __doc__  # providing that you have a docstring at the beggining of the DAG
+    dag.doc_md = """
+    This is a documentation placed anywhere
+    """  # otherwise, type it like this
     # [END documentation]
 
     # [START jinja_template]

docs/apache-airflow/tutorial.rst

@@ -184,14 +184,19 @@ Adding DAG and Tasks documentation
 ----------------------------------
 We can add documentation for DAG or each single task. DAG documentation only support
 markdown so far and task documentation support plain text, markdown, reStructuredText,
-json, yaml.
+json, yaml. The DAG documentation can be written as a doc string at the beginning of the DAG file (recommended)
+or anywhere in the file. Below you can find some examples on how to implement task and DAG docs,
+as well as screenshots:
 
 .. exampleinclude:: /../../airflow/example_dags/tutorial.py
     :language: python
     :dedent: 4
     :start-after: [START documentation]
     :end-before: [END documentation]
 
+.. image:: img/task_doc.png
+.. image:: img/dag_doc.png
+
 Setting up Dependencies
 -----------------------
 We have tasks ``t1``, ``t2`` and ``t3`` that do not depend on each other. Here's a few ways