Add a new "writing docs" section to README

TBR

Author: sethladd

README.md

@@ -27,9 +27,7 @@ Note: to ensure that this version is run when you type `dartdoc` on the command
 line, make sure that `~/.pub-cache/bin` is on your `PATH`, and before the path
 to the Dart SDK.
 
-## Running dartdoc
-
-### Generating docs
+## Generating docs
 
 Run `dartdoc` from the root directory of package.  For example:
 
@@ -55,7 +53,36 @@ Success! Docs generated into <path-to-server-code-lab>/server_code_lab/doc/api/i
 By default, the documentation is generated to the `doc/api` directory as static
 HTML files.
 
-### Viewing docs
+### Options
+
+Command-line options for dartdoc include:
+
+- `-h` or `--help` Display help.
+- `--header=<file>` Insert the specified file, which contains HTML code, into
+  the header of every page.
+- `--footer=<file>` Insert the specified file, which contains HTML code, into
+  the footer of every page.
+- `--input=<directory>` Generate the docs from the specified directory. If not
+  specified, it defaults to the current directory.
+- `--output=<directory>` Generate the output to the specified directory. If not
+  specified, it defaults to `doc/api`.
+- `--package-root=<directory>` Specify the package root of the library.
+- `--exclude=<lib1,lib2,lib3,...>` Exclude the specified libraries from the
+  generated docs.
+- `--include=<lib1,lib2,lib3,...>` Generate docs for the specified libraries.
+- `--hosted-url=<url>` Build a docs sitemap using the specified URL for your
+  website.
+- `--add-crossdart` Add links to [Crossdart](//crossdart.info) to the
+  Source Code sections.
+
+The following options are used only when generating docs for the Dart SDK.
+
+- `--dart-sdk=<path>` Specify the location of the Dart SDK, if it can't be
+  detected automatically.
+- `--sdk-docs` Generate only docs for the Dart SDK.
+- `--sdk-readme=<file>` Specify the README file for the Dart SDK.
+
+## Viewing docs
 
 You can view the generated docs directly from the file system, but if you want
 to use the search function, you must load them with an HTTP server.
@@ -71,7 +98,7 @@ $ dhttpd --path doc/api
 Navigate to `http://localhost:8080` in your browser; the search function should
 now work.
 
-## Link structure
+### Link structure
 
 dartdoc produces static files with a predictable link structure.
 
@@ -92,36 +119,15 @@ library-name/                       # : is turned into a - e.g. dart:core => dar
 
 File names are _case-sensitive_.
 
-## Options
+## Writing docs
 
-Command-line options for dartdoc include:
+Check out the
+[Effective Dart: Documentation guide](https://www.dartlang.org/effective-dart/documentation/).
 
-- `-h` or `--help` Display help.
-- `--header=<file>` Insert the specified file, which contains HTML code, into
-  the header of every page.
-- `--footer=<file>` Insert the specified file, which contains HTML code, into
-  the footer of every page.
-- `--input=<directory>` Generate the docs from the specified directory. If not
-  specified, it defaults to the current directory.
-- `--output=<directory>` Generate the output to the specified directory. If not
-  specified, it defaults to `doc/api`.
-- `--package-root=<directory>` Specify the package root of the library.
-- `--exclude=<lib1,lib2,lib3,...>` Exclude the specified libraries from the
-  generated docs.
-- `--include=<lib1,lib2,lib3,...>` Generate docs for the specified libraries.
-- `--hosted-url=<url>` Build a docs sitemap using the specified URL for your
-  website.
-- `--add-crossdart` Add links to [Crossdart](//crossdart.info) to the
-  Source Code sections.
-
-The following options are used only when generating docs for the Dart SDK.
-
-- `--dart-sdk=<path>` Specify the location of the Dart SDK, if it can't be
-  detected automatically.
-- `--sdk-docs` Generate only docs for the Dart SDK.
-- `--sdk-readme=<file>` Specify the README file for the Dart SDK.
+The guide covers formatting, linking, markup, and general best practices
+when authoring doc comments for Dart with dartdoc.
 
-## Excluding from documentation
+### Excluding from documentation
 
 dartdoc will not generate documentation for a Dart element and its children that has
 the `<nodoc>` tag in the documentation comment.