Merge branch 'errorcorrectionzoo:main' into main

CONTRIBUTING.md

@@ -3,6 +3,7 @@
 Your contribution to expanding and improving the Error Correction Zoo is very
 welcome.
 
+
 ## How to contribute content
 
 You can contribute by opening sending us an [email][eczooemail], opening an
@@ -20,6 +21,33 @@ make sure you understand the YAML file syntax and use an appropriate text editor
 to avoid YAML syntax errors (such as [Atom][atomurl]).
 
 
+## Main steps to contribute
+
+- Create a pull request with the content you'd like to propose.  Mark it as
+  a "draft" so we know you're still fine-tuning it.
+
+- Once you created the pull request, you can preview the content as you are
+  proposing in your pull request by visiting:
+
+  https://errorcorrectionzoo.org/gitpreview
+
+  Wait until the webpage loads (it can take a couple minutes).  Then, enter
+  your pull request number in the form at the bottom of the page and click
+  "Go to PR!".  Select the relevant code at the top of the page to preview
+  the code page as it will appear in the zoo if your PR is accepted.
+
+  Error messages will hopefully help you identify and locate errors in
+  your YAML files (e.g., invalid syntax).
+
+- You can update your pull request to fine-tune its contents.  To refresh
+  and reload the preview, you can simply hit "Go to PR!" again.
+
+- Once you're happy with the content you're suggesting, you can mark your
+  pull request as ready by removing the "draft" mention.  Victor might
+  also have some suggestions for you on your pull request, so make sure
+  you have your github notifications on :)
+
+
 ## Please take note:
 
 - Use [LaTeX-like formatting minilanguage][eczooflm] features to write math,
@@ -38,9 +66,10 @@ to avoid YAML syntax errors (such as [Atom][atomurl]).
   in `users/users_db.yml` in your pull request.  Only significant edits count
   in the change log; fixing typos and formatting are not recorded.
 
+
 ## Questions?
 
-Ask us! And thanks again for your interest in contributing.
+Ask us! And thanks again for your interest in contributing to the zoo.
 
 
 [eczooemail]: mailto:errorcorrectionzoo@XXXXXX?subject=code%20data&body=Please%20replace%20'@XXXXXX'%20in%20the%20email%20address%20by%20'@gmail.com'.%20Thanks%20for%20your%20message!

README.md

@@ -17,26 +17,35 @@ it!  Here's a BibTeX blurb you could use:
 
 The code meta-information is stored in YAML format, with one file per code.
 
-## The YAML language
+Jump to:
+* [What is a YAML file?](#the-zoo-data-files)
+* [Supported LaTeX-inspired syntax](#latex-inspired-mini-language-syntax)
+* [How to contribute content](#contributing)
 
-If you type in new codes, make sure you understand the basics of the
-YaML language, and be sure to use a good text editor (if you'd like
-a suggestion, check out the [Atom](https://atom.io/) text editor).
+## The Zoo data files
 
-YaML is a common markup language.  You can [google
-"YAML tutorial"](https://google.com/search?q=YaML+tutorial) or check out
-the language's [Wikipedia
-page](https://en.wikipedia.org/wiki/YAML).)
+All of the zoo entries' information are stored in data files that are both
+human and machine readable.
 
+See the `template.yml` file to get started.
 
-## Structure and hierarchy of the data files
+(@VVA: feel free to fill in more info about folder structure guidelines here)
 
-See the `template.yml` file to get started.
+### The YAML language
 
-(@VVA: feel free to fill in more info about folder structure etc. here)
+If you type in new codes, make sure you understand the basics of the
+YAML language, and be sure to use a good text editor (if you'd like
+a suggestion, check out the [Atom](https://atom.io/) text editor).
+
+YAML is a common markup language.  You can [google
+"YAML tutorial"](https://google.com/search?q=YAML+tutorial) or check out
+the language's [Wikipedia
+page](https://en.wikipedia.org/wiki/YAML).)
 
+**Note**: Be mindful of line indentation, as it is important in order
+to obtain a well-formed and unambiguous YAML file.
 
-## Text content in the YAML file
+### Text content in the YAML file
 
 By convention, we store short pieces of text as single-quoted strings, e.g.:
 
@@ -71,7 +80,7 @@ because it might interfere with possible whitespace's meaning in our
 LaTeX-inspired mini-language; for instance, leaving an empty line
 will fail to start a new paragraph.)
 
-## LaTeX-inspired mini-language in text
+## LaTeX-inspired mini-language syntax
 
 In most text fields, you can make use of LaTeX-inspired
 command syntax.  You can insert math expressions, add citations,
@@ -97,21 +106,51 @@ Example:
         Refer to equations with \eqref{eq:stabilizers}, etc. ...
 
 
+## Contributing
+
+Get in touch with Victor V Albert & feel free to submit pull requests!  You
+can also check out our more detailed
+[contributing guidelines](https://github.com/errorcorrectionzoo/eczoo_data/blob/main/CONTRIBUTING.md).
 
-## Building and previewing the site
+The main steps to contribute content are:
+
+- Create a pull request with the content you'd like to propose.  Mark it as
+  a "draft" so we know you're still fine-tuning it.
+
+- Once you created the pull request, you can preview the content as you are
+  proposing in your pull request by visiting:
+
+  https://errorcorrectionzoo.org/gitpreview
+
+  Wait until the webpage loads (it can take a couple minutes).  Then, enter
+  your pull request number in the form at the bottom of the page and click
+  "Go to PR!".  Select the relevant code at the top of the page to preview
+  the code page as it will appear in the zoo if your PR is accepted.
+
+  Error messages will hopefully help you identify and locate errors in
+  your YAML files (e.g., invalid syntax).
+
+- You can update your pull request to fine-tune its contents.  To refresh
+  and reload the preview, you can simply hit "Go to PR!" again.
+
+- Once you're happy with the content you're suggesting, you can mark your
+  pull request as ready by removing the "draft" mention.  Victor might
+  also have some suggestions for you on your pull request, so make sure
+  you have your github notifications on :)
+
+
+## Building and previewing the site locally
 
 To build and preview the site locally, follow the instructions given
 in the [`eczoo_sitegen`
 repository](https://github.com/errorcorrectionzoo/eczoo_sitegen).
 
 
-## Contributing
-
-Get in touch with Victor V Albert & feel free to submit pull requests!  Check
-out our [contributing guidelines](https://github.com/errorcorrectionzoo/eczoo_data/blob/main/CONTRIBUTING.md).
-
+## I want to create the <Your Favorite Topic> Zoo. How did you build the EC Zoo and can I reuse your code?
 
-## I want to create the <Your Favorite Topic> Zoo. How did you build the EC Zoo and can I reuse your code?
+The error correction zoo is based on [ZooDb JS library framework](https://github.com/phfaist/zoodb).  You
+are welcome to use develop your own Zoo based on this library.  Consider starting with [this simple toy
+example of a zoo built with ZooDb](https://github.com/phfaist/zoodb-example).
 
-Get in touch with me, I'll be happy to point to the basic tools we used and how they
+Get in touch with me! I'll be happy to point to the basic tools we used and how they
 can be reused to build other zoos (contact info at https://phfaist.com/).