DOCS: Documentation Style Guide (#2383)

Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>

documentation/SUMMARY.md

@@ -154,7 +154,8 @@
 
 ## Developer info
 
-* [Style Guide](styleguide.md)
+* [Code Style Guide](styleguide-code.md)
+* [Documentation Style Guide](styleguide-doc.md)
 * [DNSControl is an opinionated system](opinions.md)
 * [Writing new DNS providers](writing-providers.md)
 * [Creating new DNS Resource Types (rtypes)](adding-new-rtypes.md)

documentation/adding-new-rtypes.md

@@ -60,14 +60,14 @@ a minimum.
 -   Run stringer to auto-update the file `dnscontrol/providers/capability_string.go`
 
 ```shell
-pushd; cd providers;
+pushd; cd providers/;
 stringer -type=Capability
 popd
 ```
 alternatively
 
 ```shell
-pushd; cd providers;
+pushd; cd providers/;
 go generate
 popd
 ```
@@ -180,7 +180,7 @@ See also `017-txt.js`.
 Run these tests via:
 
 ```shell
-cd dnscontrol/pkg/js
+cd pkg/js/
 go test ./...
 ```
 
@@ -252,7 +252,7 @@ in the source code.
 To run the integration test with the BIND provider:
 
 ```shell
-cd dnscontrol/integrationTest
+cd integrationTest/
 go test -v -verbose -provider BIND
 ```
 

documentation/markdown-examples/code/dnsconfig-code-example-with-filename.md

@@ -0,0 +1,10 @@
+{% code title="dnsconfig.js" %}
+```javascript
+var REG_NONE = NewRegistrar('none');
+var DNS_BIND = NewDnsProvider('bind');
+
+D('example.com', REG_NONE, DnsProvider(DNS_BIND),
+    A('@', '1.2.3.4')
+);
+```
+{% endcode %}

documentation/markdown-examples/code/dnsconfig-code-example-without-filename.md

@@ -0,0 +1,10 @@
+{% code %}
+```javascript
+var REG_NONE = NewRegistrar('none');
+var DNS_BIND = NewDnsProvider('bind');
+
+D('example.com', REG_NONE, DnsProvider(DNS_BIND),
+    A('@', '1.2.3.4')
+);
+```
+{% endcode %}

documentation/markdown-examples/hint/hint-danger.md

@@ -0,0 +1,3 @@
+{% hint style="danger" %}
+**Danger hints** are good for highlighting destructive actions or raising attention to critical information.
+{% endhint %}

documentation/markdown-examples/hint/hint-info.md

@@ -0,0 +1,3 @@
+{% hint style="info" %}
+**Info hints** are great for showing general information, or providing tips and tricks.
+{% endhint %}

documentation/markdown-examples/hint/hint-success.md

@@ -0,0 +1,3 @@
+{% hint style="success" %}
+**Success hints** are good for showing positive actions or achievements.
+{% endhint %}

documentation/markdown-examples/hint/hint-warning.md

@@ -0,0 +1,3 @@
+{% hint style="warning" %}
+**Warning hints** are good for showing important information or non-critical warnings.
+{% endhint %}

documentation/providers/hexonet.md

@@ -57,7 +57,7 @@ dnscontrol get-zones --format=nameonly hexonet HEXONET  all
 ```
 ```shell
 # Review the output.  Pick one domain and set HEXONET_DOMAIN.
-cd $GIT/dnscontrol/integrationTest
+cd integrationTest/
 export HEXONET_DOMAIN=yodream.com            # Pick a domain name.
 export HEXONET_ENTITY=OTE
 export HEXONET_UID=test.user

documentation/release-engineering.md

@@ -235,7 +235,7 @@ Build the software:
 {% endhint %}
 
 ```shell
-cd docs/flattener
+cd docs/flattener/
 export GOPHERJS_GOROOT="$(go1.17.1 env GOROOT)"
 export GOOS=linux
 gopherjs build

documentation/styleguide-doc.md

@@ -0,0 +1,201 @@
+# Documentation Coding Style
+
+## Where are the docs?
+
+TL;DR version: [`docs`](https://github.com/StackExchange/dnscontrol/tree/master/docs) is the [marketing website](https://dnscontrol.org). [`documentation`](https://github.com/StackExchange/dnscontrol/tree/master/documentation) is the [docs.dnscontrol.org](https://docs.dnscontrol.org/) website. (Yes, the names are backwards!)
+
+**The two websites**
+
+1. <https://dnscontrol.org/>
+   * The main website
+   * Source code: [`docs`](https://github.com/StackExchange/dnscontrol/tree/master/docs)
+   * Mostly "marketing" for the project.
+   * Rarely changes.  Updated via GitHub "pages" feature.
+2. <https://docs.dnscontrol.org/>
+   * Project documentation
+   * Source code: [`documentation`](https://github.com/StackExchange/dnscontrol/tree/master/documentation)
+   * Users and developer documentation
+   * Changes frequently.  Updated via [GitBook](https://www.gitbook.com/)
+
+**The directory structure**
+
+Within the git repo, docs are grouped:
+
+* [`documentation/`](https://github.com/StackExchange/dnscontrol/tree/master/documentation): general docs
+* [`documentation/providers/`](https://github.com/StackExchange/dnscontrol/tree/master/documentation/providers/): One file per provider
+* [`documentation/functions/`](https://github.com/StackExchange/dnscontrol/tree/master/documentation/functions/): One file per `dnsconfig.js` language feature
+* [`documentation/assets/FOO/`](https://github.com/StackExchange/dnscontrol/tree/master/documentation/assets/): Images for page FOO(PNGs only, please!)
+
+## How to add a new page?
+
+1. Add the page to the `documentation` folder (possibly a sub folder)
+2. List the page in `SUMMARY.md` so that it will appear in the table of contents, sidebar, etc.
+
+## Documentation previews
+
+> "Preview links are only accessible by GitBook users. We're working on a feature that will allow preview links to be viewable by anyone who accesses the PR." — _[GitBook](https://docs.gitbook.com/product-tour/git-sync/github-pull-request-preview#how-to-access-preview-links)_
+
+## Formatting tips
+
+### General
+
+Break lines every 80 chars.
+
+Include a blank line between paragraphs.
+
+Leave one blank line before and after a heading.
+
+Javascript code should use double quotes (`"`) for strings, not single quotes
+(`'`).  They are equivalent but consistency is good.
+
+### Headings
+
+```markdown
+#  Title of the page
+
+## Heading
+
+At least one paragraph.
+
+## Subheadings
+
+At least one paragraph.
+
+* **Step 1: Foo**
+
+Description of the step.
+
+* **Step 2: Bar**
+
+Description of the step.
+
+(further sub sub headings are discouraged encouraged)
+```
+
+### Code Snippets
+
+See the examples below, for the Markdown syntax click on the 'Source code'.
+
+Long example: (with filename)
+
+{% code title="dnsconfig.js" %}
+```javascript
+var REG_NONE = NewRegistrar('none');
+var DNS_BIND = NewDnsProvider('bind');
+
+D('example.com', REG_NONE, DnsProvider(DNS_BIND),
+    A('@', '1.2.3.4')
+);
+```
+{% endcode %}
+
+[Source code](markdown-examples/code/dnsconfig-code-example-with-filename.md?plain=1)
+
+Long example: (without filename)
+
+{% code %}
+```javascript
+var REG_NONE = NewRegistrar('none');
+var DNS_BIND = NewDnsProvider('bind');
+
+D('example.com', REG_NONE, DnsProvider(DNS_BIND),
+    A('@', '1.2.3.4')
+);
+```
+{% endcode %}
+
+[Source code](markdown-examples/code/dnsconfig-code-example-without-filename.md?plain=1)
+
+### Hint
+
+Hints are a great way to bring the reader's attention to specific elements in your documentation.
+
+There are 4 different types of hints, and both inline content and formatting are supported.
+
+### Example of a hint
+
+{% hint style="info" %}
+**Info hints** are great for showing general information, or providing tips and tricks.
+{% endhint %}
+
+ [Source code](markdown-examples/hint/hint-info.md?plain=1)
+
+{% hint style="success" %}
+**Success hints** are good for showing positive actions or achievements.
+{% endhint %}
+
+ [Source code](markdown-examples/hint/hint-success.md?plain=1)
+
+{% hint style="warning" %}
+**Warning hints** are good for showing important information or non-critical warnings.
+{% endhint %}
+
+ [Source code](markdown-examples/hint/hint-warning.md?plain=1)
+
+{% hint style="danger" %}
+**Danger hints** are good for highlighting destructive actions or raising attention to critical information.
+{% endhint %}
+
+ [Source code](markdown-examples/hint/hint-danger.md?plain=1)
+
+{% hint style="info" %}
+### This is a heading
+
+This is a line
+
+This is a second <mark style="color:white;background-color:green;">line</mark>
+{% endhint %}
+
+### Technical references
+
+#### Mentioning language features
+
+Not every mention to A, CNAME, or function
+needs to be a link to the manual for that record type.
+However, the first mention on a page should always
+be a link.  Others are at the authors digression.
+
+```markdown
+The [`PTR`](functions/domain/PTR.md) feature is helpful in LANs.
+```
+
+#### Mentioning functions from the Source code
+
+```markdown
+The function `GetRegistrarCorrections()` returns...
+```
+
+### Links
+
+#### Internal links
+
+```markdown
+Blah blah blah [M365_BUILDER](functions/record/M365_BUILDER.md)
+```
+
+{% hint style="info" %}
+**NOTE**: The `.md` is required.
+{% endhint %}
+
+#### Link to another website
+
+Just list the URL.
+
+```markdown
+Blah blah blah <https://www.google.com> blah blah.
+```
+
+#### Link with anchor text
+
+```markdown
+Blah blah blah [a search engine](https://www.google.com) blah blah.
+```
+
+## Proofreading
+
+Please spellcheck documents before submitting a PR.
+
+Don't be surprised if Tom rewrites your text.  He often does that to keep the
+documentation consistent and make it more approachable by new users.  It's not
+[because he has a big ego](https://www.amazon.com/stores/author/B004J0QIVM).
+Well, not usually.

documentation/writing-providers.md

@@ -168,7 +168,6 @@ complex algorithms in the new code.
 
 Run the unit tests with this command:
 
-    cd dnscontrol
     go test ./...
 
 
@@ -182,7 +181,7 @@ Integration tests use a test account and a real domain.
 For example, this will run the tests using BIND:
 
 ```shell
-cd dnscontrol/integrationTest
+cd integrationTest/
 go test -v -verbose -provider BIND
 ```