Merge branch 'master' of https://tree.clementinecomputing.com/clementinecomputing/Popufare-Auxiliary-Documentation

notes/Documentation-Notes.md

@@ -0,0 +1,56 @@
+Documentation Notes
+===
+
+This is a "meta" document about the process of writing
+documentation.
+
+Four Types of Documentation
+---
+
+[src](https://www.divio.com/blog/documentation/)
+
+* Tutorials
+  - learning oriented (lessons)
+  - let user learn by doing
+* How-To Guides
+  - goal oriented
+  - shows how to solve a specific problem
+* Explanation
+  - understanding oriented
+  - provided history, background and context
+* Reference
+  - information oriented
+  - accurate and complete
+  - assumes knowledge about motivation and structure of project
+
+Outline of Documentation for Popufare
+---
+
+I'm having trouble differentiating "Learning" from "How-to".
+Maybe the "Learning" category should be more about broader
+topics that only tangentially relate to Popufare and "How-tos"
+should be specific on how to get aspects of Popufare working.
+
+* How-to
+  - How to setup a test server and test DIU
+    + How to setup a test database
+    + How to setup a test server/Docker image
+    + How to setup a test docker bus fare image (separate from the server)
+  - How to Setup a DIU and PIU hardware system
+  - How to customize the Popufare system for your own organization
+* Reference
+  - Ridelogic/Popufare API
+  - Popufare Database tables
+  - DIU services
+    + billing local database description
+    + passes local database description
+  - Port mapping
+* Explanation
+  - Give overview of project and what each of the components does and how they
+    interact
+  - This is where larger diagrams go and high level overview comes in
+
+References
+---
+
+* [divio.com Documentation](https://www.divio.com/blog/documentation/)

rfc/tools.ietf.org-rfc-rfc2119.txt

@@ -0,0 +1,171 @@
+
+
+
+
+
+
+Network Working Group                                         S. Bradner
+Request for Comments: 2119                            Harvard University
+BCP: 14                                                       March 1997
+Category: Best Current Practice
+
+
+        Key words for use in RFCs to Indicate Requirement Levels
+
+Status of this Memo
+
+   This document specifies an Internet Best Current Practices for the
+   Internet Community, and requests discussion and suggestions for
+   improvements.  Distribution of this memo is unlimited.
+
+Abstract
+
+   In many standards track documents several words are used to signify
+   the requirements in the specification.  These words are often
+   capitalized.  This document defines these words as they should be
+   interpreted in IETF documents.  Authors who follow these guidelines
+   should incorporate this phrase near the beginning of their document:
+
+      The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
+      NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
+      "OPTIONAL" in this document are to be interpreted as described in
+      RFC 2119.
+
+   Note that the force of these words is modified by the requirement
+   level of the document in which they are used.
+
+1. MUST   This word, or the terms "REQUIRED" or "SHALL", mean that the
+   definition is an absolute requirement of the specification.
+
+2. MUST NOT   This phrase, or the phrase "SHALL NOT", mean that the
+   definition is an absolute prohibition of the specification.
+
+3. SHOULD   This word, or the adjective "RECOMMENDED", mean that there
+   may exist valid reasons in particular circumstances to ignore a
+   particular item, but the full implications must be understood and
+   carefully weighed before choosing a different course.
+
+4. SHOULD NOT   This phrase, or the phrase "NOT RECOMMENDED" mean that
+   there may exist valid reasons in particular circumstances when the
+   particular behavior is acceptable or even useful, but the full
+   implications should be understood and the case carefully weighed
+   before implementing any behavior described with this label.
+
+
+
+
+
+Bradner                  Best Current Practice                  [Page 1]
+
+RFC 2119                     RFC Key Words                    March 1997
+
+
+5. MAY   This word, or the adjective "OPTIONAL", mean that an item is
+   truly optional.  One vendor may choose to include the item because a
+   particular marketplace requires it or because the vendor feels that
+   it enhances the product while another vendor may omit the same item.
+   An implementation which does not include a particular option MUST be
+   prepared to interoperate with another implementation which does
+   include the option, though perhaps with reduced functionality. In the
+   same vein an implementation which does include a particular option
+   MUST be prepared to interoperate with another implementation which
+   does not include the option (except, of course, for the feature the
+   option provides.)
+
+6. Guidance in the use of these Imperatives
+
+   Imperatives of the type defined in this memo must be used with care
+   and sparingly.  In particular, they MUST only be used where it is
+   actually required for interoperation or to limit behavior which has
+   potential for causing harm (e.g., limiting retransmisssions)  For
+   example, they must not be used to try to impose a particular method
+   on implementors where the method is not required for
+   interoperability.
+
+7. Security Considerations
+
+   These terms are frequently used to specify behavior with security
+   implications.  The effects on security of not implementing a MUST or
+   SHOULD, or doing something the specification says MUST NOT or SHOULD
+   NOT be done may be very subtle. Document authors should take the time
+   to elaborate the security implications of not following
+   recommendations or requirements as most implementors will not have
+   had the benefit of the experience and discussion that produced the
+   specification.
+
+8. Acknowledgments
+
+   The definitions of these terms are an amalgam of definitions taken
+   from a number of RFCs.  In addition, suggestions have been
+   incorporated from a number of people including Robert Ullmann, Thomas
+   Narten, Neal McBurnett, and Robert Elz.
+
+
+
+
+
+
+
+
+
+
+
+
+Bradner                  Best Current Practice                  [Page 2]
+
+RFC 2119                     RFC Key Words                    March 1997
+
+
+9. Author's Address
+
+      Scott Bradner
+      Harvard University
+      1350 Mass. Ave.
+      Cambridge, MA 02138
+
+      phone - +1 617 495 3864
+
+      email - sob@harvard.edu
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bradner                  Best Current Practice                  [Page 3]
+