[Admin] Add style guide to contributing.md (ethereum#96)

CONTRIBUTING.md

@@ -10,15 +10,28 @@
 
 Your first PR should be a complete draft of the README.md for your namespace with at least CAIP-2 addressed, but we also welcome additional CAIPs. 
 An editor will manually review the first PR for a new CAN and assign it a number before merging it. 
-Make sure you include a `discussions-to` header with the URL to a discussion forum or open GitHub issue where people can discuss the CAN as a whole; if you requested feedback from other teams or counterparties in your namespace before submitting, a private fork of the namespaces repo containing these discussions is a perfectly valid and helpful `discussions-to` entry.
-Note that `discussions-to` can be a single value or an array, too much discussion is more helpful than not enough.
-It is also acceptable to tag interlocutors and reviewers familiar with the namespace in the initial PR; you may be asked to do so by the editors.
+Make sure you include a `discussions-to` header with one or more URLs a GitHub issue, GitHub Discussion, or other forum where people can discuss the CAN going forward; if you requested feedback from other teams or counterparties in your namespace before submitting, an issue or discussion on a fork of the namespaces repo is also a helpful addition to the `discussions-to` entry, which can be an array.
+It is also acceptable to tag interlocutors and reviewers familiar with the namespace in the initial PR; you may be asked to do so later by the editors if they are not familiar with the community.
 
 If your CAN requires images, the image files should be included in a subdirectory of the `assets` folder for that CAN as follows: `assets/namespace-N` (where **N** is to be replaced with the CAN name).
 When linking to an image in the CAN, use relative links such as `../assets/namespace-{N}/image.png`.
 
 It is greatly appreciated if you can render your PR locally to check the Jekyll syntax; to do so, run `bundle exec jekyll serve`.
 
+## Style Guide
+
+Github-flavored Markdown is encouraged for all CAIP documents, with the following conventions observed:
+
+Line breaks:
+- One line per sentence (or independent clause in the case of semicolons) makes for easier parsing of diffs in PR review and is preferred but not required
+
+Link formatting:
+- All external documents cited should be defined at the end of the `## References` section of each document, one per line, in the form `[CAIP-1]: https://chainAgnostic.org/CAIPs/CAIP-1` - these link alias definitions are invisible in rendered markdown, but serves as footnotes to readers viewing the files in a text editor.
+- All references to other namespaces or to CAIPs should refer to the rendered form on the domain controlled by CASA (e.g. `https://chainagnostic.org/CAIPs/caip-104`) rather than to the current public git repository that it renders from (currently, `https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-104.md?plain=1`, but subject to change)
+- All references elsewhere in the text should be by link-alias (e.g. `[CAIP Syntax][CAIP-1]`) rather than self-contained (e.g. `[CAIP syntax](https://ChainAgnostic.org/CAIPs/caip-1)`); note that in this example, `[CAIP-1][CAIP-1]`, `[CAIP-1][]` and `[CAIP-1]` will all link to the same URL if the alias has been defined elsewhere in the document when rendered. This makes the document easier to read in a text editor.
+- Links to other sections should always take the form of markdown section heading links rather than HTML anchors or any other reference, e.g. `For further detail, see the [Security Considerations section](#security-considerations)`
+- Providing lists of normative and non-normative references according to, e.g., the [IETF style guide for references](https://www.ietf.org/archive/id/draft-flanagan-7322bis-07.html#section-4.8.6) is welcomed but not required; a short list of useful documents or additional resources with captions or explanations is also welcome.
+
 ## References
 
 [CAIP-2]: https://chainagnostic.org/CAIPs/caip-2

README.md

@@ -5,7 +5,7 @@ They consist of a 1 high-level "README.md" file to contextualize the ecosystem,
 Each "CAIP profile" defines the namespace's syntax, semantics, and context for that CAIP (i.e., it's address format, actor model, asset addressing model, etc.).
 The intended audience of both the general "README.md" and each profile is a developer familiar with the CAIP being profiled but not familiar with the ecosystem being described, so the best namespaces provide all the links and entry-level explanations of the context needed for developers to build wallet and/or dapp interfaces that interact with assets, contracts, and accounts of a given namespace.
 
-The namespaces are best read on the [namespaces][] "docs" website rather than in github. To contribute see the [Contributing file](./CONTRIBUTING.md).
+The namespaces are best read as rendered on the [namespaces][] website rather than in github. To contribute see the [Contributing file](./CONTRIBUTING.md).
 
 ## How it works
 Each namespace implements one or more [CAIPs](https://github.com/ChainAgnostic/CAIPs). The most important CAIPs to consider for a namespace are: