Update Readme and Contributing pages

With details about how issues are being used for discussion,
and markup style notes and references.

Author: AmeliaBR

CONTRIBUTING.md

@@ -2,6 +2,43 @@
 
 This repository is being used for work in the [W3C Maps For HTML Community Group](https://www.w3.org/community/maps4html/), governed by the [W3C Community License Agreement (CLA)](https://www.w3.org/community/about/agreements/cla/). To make substantive contributions, you must join the CG. 
 
+## Before making a pull request…
+
+Is it a simple fix, like a typo or an obvious code correction? Go right ahead with a PR.
+
+If it's anything bigger, please start an issue to discuss it first.
+You'll also need to join the community group and agree to the IP (intellectual property) commitments.
+If you have an employer, you'll either need to get your employer to join the group or you'll need to inform the W3C that your employer doesn't have any IP claims over the work you're contributing.
+
+If you're discussing changes to an existing use case, reference tool, or capability section, check to see if there is already a discussion issue open.
+
+## Markup style
+
+The main report is in the index.html file.
+
+The report uses the [ReSpec](https://github.com/w3c/respec/wiki) specification generator,
+with custom code to generate tags, support info, and cross links between use cases and capabilities.
+
+For new use cases and capabilities, there are templates at the bottom of the document.
+Copy & paste the `<section>` elements from these templates into place,
+then replace the comments with the relevant content.
+
+The report uses [semantic line breaking](https://sembr.org/):
+wrap text at the end of every sentence,
+and break long sentences after punctuation or other logical separations in the content.
+This makes it easier to track edits using commit diffs.
+
+Other code style notes:
+
+- Start and end tags for paragraphs and sectioning elements go on their own line.
+- Headings, definition terms, and short list items can have markup and text on the same line.
+- Use explicit section elements with `id` values for headings h4 and higher.
+- Leave a single empty line between sections or before an h5 heading.
+- Don't indent markup for regular body text.
+- Use ReSpec auto links wherever possible, especially for references.
+
+## Collaboration
+
 If you are not the sole contributor to a contribution (pull request), please identify all 
 contributors in the pull request comment.
 

README.md

@@ -1,16 +1,29 @@
-# HTML-Map-Element-UseCases-Requirements
-Use cases and requirements for Maps on the Web
+# Use Cases and Requirements for Maps on the Web
 
-This is the home of the current version of the [Use Cases and Requirements for Standardizing Web Maps](https://maps4html.github.io/HTML-Map-Element-UseCases-Requirements/).
+This is the home for development of the report [Use Cases and Requirements for Standardizing Web Maps](https://maps4html.github.io/HTML-Map-Element-UseCases-Requirements/)
+by the [W3C Maps For HTML Community Group](https://www.w3.org/community/maps4html/).
 
 ## Found a bug? Want to contribute something? 
 If you found a problem with the document, no matter how small, 
 please [file a bug](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues).
 
+Issues are also being used to discuss the content of
+[use cases](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues?q=is%3Aissue+is%3Aopen+label%3A%22discussion%3A+use+case%22),
+[reference JavaScript implementations](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues?q=is%3Aopen+is%3Aissue+label%3A%22discussion%3A+sample+JS+tool%22),
+and [capabilities (potential requirements)](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues?q=is%3Aissue+is%3Aopen+label%3A%22discussion%3A+capability%22),
+among [other topics](https://github.com/Maps4HTML/HTML-Map-Element-UseCases-Requirements/issues?&q=is%3Aissue+is%3Aopen+-label%3A%22discussion%3A+use+case%22+-label%3A%22discussion%3A+capability%22+-label%3A%22discussion%3A+sample+JS+tool%22).
+The [draft report](https://maps4html.github.io/HTML-Map-Element-UseCases-Requirements/)
+includes cross references to the discussion page for each section.
+
+Use those issues to suggest changes to the text, the references and examples, or to the conclusions (which tags apply to which capability and should the capability be a requirement).
+
+Start a new issue to suggest a new use case or capability.
+
 See also our [contributor's guide](CONTRIBUTING.md).
 
-Proposals for normative changes to the specification should take 
-place on the [Maps4HTML mailing list](mailto:[email protected]).
+Broader discussion about the community group projects,
+and how this report relates to other activities,
+should take place on the [Maps4HTML mailing list](mailto:[email protected]).
 
 ## Let me see it! 
 It's on [github pages, here](https://maps4html.github.io/HTML-Map-Element-UseCases-Requirements/).