Merge 608e287 into 2999b5f

docs/adoptability.md

@@ -216,7 +216,7 @@ that distinction is important.
   very seriously and therefore obtains CVE numbers even for small,
   trivial security problems that don't really put user data at risk.
 
-**KEY RECOMMENDATION**: [Search the CVE
+  **KEY RECOMMENDATION**: [Search the CVE
   list](https://cve.mitre.org/find/search_tips.html) to see how
   well-represented the product you're considering is in the CVE
   database.
@@ -437,8 +437,12 @@ from/to it.
 
 It is unfortunate that such a key concept is hidden behind the
 technical acronym 'API.'  If you aren't already familiar with what
-APIs do, please take a moment to read the Introduction to APIs for
-Non-Technical Readers section in the [Appendix: APIs](appendix-apis.md#appendix-introduction-to-apis-for-non-technical-readers) as well as the example of Open Referral in the [Appendix: Examples](appendix-examples.md#appendix-examples), then come back here.
+APIs do, please take a moment to read the "Introduction to APIs for
+Non-Technical Readers" section in the [Appendix:
+APIs](appendix-apis.md#appendix-introduction-to-apis-for-non-technical-readers)
+as well as the example of Open Referral in the [Appendix:
+Examples](appendix-examples.md#appendix-examples), then come back
+here.
 
 Having a documented API as part of a service is very important.  APIs
 make many things possible. The read-only side of an API enables
@@ -860,9 +864,9 @@ should be messy and quick -- a year from now it will probably be out
 of date, and that's okay.  Just hand-draw it on paper or on a
 whiteboard.
 
-Here is a map drawn to identify stakeholders in the [Arches
-Project](https://archesproject.org/). The original was hand-drawn,
-but we cleaned up a bit for publication:
+The figure below is a map drawn to identify stakeholders in the
+[Arches Project](https://archesproject.org/).  The original was
+hand-drawn, but we cleaned up a bit for publication.
 
 ![Ecosystem map for the Arches Project (https://archesproject.org/).](/img/example-ecosystem-map-768x550.png)
 
@@ -923,90 +927,95 @@ simple, unprioritized checklist.
 **Does the product meet your functional requirements?**
 
 - Do the functional Application Programming Interfaces (APIs) you’ll need exist, 
-and are they well documented? Can you find examples of these APIs being used in 
-ways similar to your plans?
+  and are they well documented? Can you find examples of these APIs being used in 
+  ways similar to your plans?
 - Will your data be portable? 
     - Can you extract or import non-PII data in a non-proprietary format? (a 
-    requirement of the DPG standard!)
+      requirement of the DPG standard!)
     - Can you import and export data in the formats you expect to need? 
     - Can you generally import and export data with an acceptable level of pre- 
-    and post- action cleaning and manipulation? 
+      and post- action cleaning and manipulation? 
 - Is the product extensible? 
     - Do many extensions exist, and are they being used? 
     - If you are evaluating a vendor to help you with an extensible
       product, does the vendor have a history of creating successful
       extensions for others?
 
 **Does the product meet your requirements for technical quality?** 
+
 - Is the product as secure as possible? 
     - Is there a documented process for reporting security vulnerabilities?
     - Are there published security patch releases? Is there a published process 
-    for publishing these patches? 
+      for publishing these patches? 
     - Are any third-party dependencies updated? 
     - Does the project publish Common Vulnerability Exposure (CVE) number(s)? 
       (usually most relevant for more mature projects) 
     - Does the project publish security audits? (usually most relevant for more 
-    mature projects) 
+      mature projects) 
 - Is the product stable and reliable? 
-   -  What’s your analysis based on bug reports? 
+    - What’s your analysis based on bug reports? 
     - What's your analysis of public conversations around the product? 
     - Do commercial vendors offer services around the product? 
 - Is the product scalable enough? 
     - First, do you understand the scale you’ll require from the product? 
     - Does the default product configuration meet your needs? 
     - If not, is there an indication -- through formal documentation, product 
-    reviews, conversations in user forums, etc. -- that the product can scale to 
-    your needs?
-     - Can you invest appropriately to deploy and support the DPG to meet your 
-     scalability requirements? 
-     - Again, do Application Programming Interfaces (APIs) exist and are they 
-     well documented? Can you find public examples of the product’s APIs being 
-     used for the level of scale you’ll need? 
+      reviews, conversations in user forums, etc. -- that the product can scale to 
+      your needs?
+    - Can you invest appropriately to deploy and support the DPG to meet your 
+      scalability requirements? 
+    - Again, do Application Programming Interfaces (APIs) exist and are they 
+      well documented? Can you find public examples of the product’s APIs being 
+      used for the level of scale you’ll need? 
 
 **Does the project seem to be sustainable?** 
+
 - Are there diverse, resource-committing participants?
-- Based on a rough idea of the project's archetype, do you see the predicted types 
-of participants?  
-- Are there commercial participants? 
+- Based on a rough idea of the project's archetype, do you see the predicted types
+  of participants?
+- Are there commercial participants?
 - What are the gaps and opportunities you see based on a project ecosystem map?  
-How might these impact sustainability?   
+  How might these impact sustainability?   
 
 **Does the project seem responsive to user needs?**
+
 - Are bug reports generally processed in a timely fashion? (note that not all 
-bugs can be fixed quickly, but the bug reporting system should still give you 
-a good indication of attention)
+  bugs can be fixed quickly, but the bug reporting system should still give you 
+  a good indication of attention)
 - Are contributions welcomed? 
 - Are there ways for participants to influence the roadmap? 
 - When security vulnerabilities arise, does the project handle them promptly and 
-competently? 
+  competently? 
 - Are there community participation guidelines, and are they enforced?
 
 **Will the project provide the level of support you require?**
+
 - Is the documentation around system installation and initial configuration of 
-high quality?
+  high quality?
 - Overall, is documentation clear and updated? 
 - Are there commercial support providers around the product?
 - If so, are they engaged in the project's development community?
 - Are there active user forums? (e.g. non-commercial support)
 
 
-**FUTURE WORK**: More in-depth evaluation templates might be useful to create 
-in the future as 
-this toolkit is further tested and revised. The first suggestion is 
-a scoring and ranking template to help agencies use the points outlined in this 
-section to more deeply assess open source products for adoption as a standalone 
-DPG or as components in a new DPG. The second is an internal capacity assessment 
-template aimed at 
-helping agencies evaluate their ability to leverage the toolkit’s broader set of 
-recommendations. These potential templates would be separate but equally important 
-tools for decision making and planning.  Such templates should start simply, but 
-we can imagine that different weighting prioritizations might eventually develop 
-depending on the application area, the desired social impact, or whether an agency 
-is adopting a product generally “as is” or using it as a component. For example, 
-an agency might place greater value on the implementation experience of a 
-contracting vendor with a specific open source product if that product will be 
-adopted wholesale versus as a component in a new DPG. The latter scenario might 
-place more weight on the agency’s internal capacity to manage various open source 
+**FUTURE WORK**: More in-depth evaluation templates might be useful to
+create in the future as this toolkit is further tested and
+revised. The first suggestion is a scoring and ranking template to
+help agencies use the points outlined in this section to more deeply
+assess open source products for adoption as a standalone DPG or as
+components in a new DPG. The second is an internal capacity assessment
+template aimed at helping agencies evaluate their ability to leverage
+the toolkit’s broader set of recommendations. These potential
+templates would be separate but equally important tools for decision
+making and planning.  Such templates should start simply, but we can
+imagine that different weighting prioritizations might eventually
+develop depending on the application area, the desired social impact,
+or whether an agency is adopting a product generally “as is” or using
+it as a component. For example, an agency might place greater value on
+the implementation experience of a contracting vendor with a specific
+open source product if that product will be adopted wholesale versus
+as a component in a new DPG. The latter scenario might place more
+weight on the agency’s internal capacity to manage various open source
 components.
 
 Lastly, there might be value in extending these templates to evaluate the 

docs/appendix-examples.md

@@ -46,7 +46,7 @@ in response to Ebola outbreaks in multiple countries.
 
 ### Lutece
 
-This [https://www.lutece.paris.fr/](government services portal) was
+The [Lutece government services portal](https://www.lutece.paris.fr/) was
 developed by the city of Paris, France and has recently become the
 subject of international attention, as they make greater efforts to
 support multi-jurisdictional adoption.

docs/appendix-resources-tools.md

@@ -45,9 +45,8 @@ and helpful to you online.
 
 **Benefits of Open Source**
 
-* The World Bank report [Open Source for Global Public
-  Goods](https://openknowledge.worldbank.org/handle/10986/33401)
-  (2019) gives an overview of the benefits of open source, along with
+* The World Bank report [Open Source for Global Public Goods](https://openknowledge.worldbank.org/handle/10986/33401) (2019) 
+  gives an overview of the benefits of open source, along with
   sensible operational advice -- especially for those working in
   resource-constrained environments -- and a few case studies around
   Identification for Development (ID4D).  It reiterates many of the
@@ -225,7 +224,7 @@ manager](https://www.kobotoolbox.org/join-our-team/project-community-engagement-
 from the the team behind the Kobo Toolbox DPG (accessed Sept. 2021).
 
 **Clear guidance around *how* to contribute and what the project is looking 
-for with contributions** is as important as community governance and management.  
+for with contributions** is as important as community governance and management.
 The UNICEF Innovation team maintains a [public repository of best practices and 
 resources](https://github.com/unicef/inventory) around working 'openly' in creating 
 and managing digital public goods that includes some tips on how to write good 

docs/appendix-sample-contract.md

@@ -17,14 +17,14 @@ Below is an example **Statement of Work** for an open-source project that includ
 
 Following the open-sourcing of Software, Vendor proposes to assist Client State to:
 
-   - Monitor and improve deployability: Monitor and advise on Software's deployability by other jurisdictions; improve Software's deployability as needed.
-  - Improve deployment process: Analyze, improve, and document Software's deployment process.
-  - Manage third-party contributions: Help manage code contributions and other contributions from third-party contributors.
+- Monitor and improve deployability: Monitor and advise on Software's deployability by other jurisdictions; improve Software's deployability as needed.
+- Improve deployment process: Analyze, improve, and document Software's deployment process.
+- Manage third-party contributions: Help manage code contributions and other contributions from third-party contributors.
 - Assist with public communications: Help inform governments and the civic technology community about Software's availability and capabilities.
- - Plan and advise on long-term maintenance: Help find or create an appropriate long-term home for the Software source code and related assets, to support long-term maintenance while also ensuring that State's needs with respect to Software continue to be met.  This involve forming or joining a consortium.
- - Develop open-source contracting and procurement language: See description below.
- - Advise on open source / open technology processes: See description below.
- - Hackathons / Events: Organize and/or assist in organizing hackathons and other events to promote actionable interest in Software.
+- Plan and advise on long-term maintenance: Help find or create an appropriate long-term home for the Software source code and related assets, to support long-term maintenance while also ensuring that State's needs with respect to Software continue to be met.  This involve forming or joining a consortium.
+- Develop open-source contracting and procurement language: See description below.
+- Advise on open source / open technology processes: See description below.
+- Hackathons / Events: Organize and/or assist in organizing hackathons and other events to promote actionable interest in Software.
 
 This proposed Statement of Work describes mainly ongoing processes. Although each process will likely have specific deliverables associated with it, not all of those deliverables can be predicted in advance. Therefore, this SOW proposes activities with time boundaries, not with the intention of ending the work when the time limit is reached, but to give State a scheduled checkpoint to assess the quality and direction of the work so far, with the option to extend and/or amend the contract if desired.
 
@@ -46,14 +46,14 @@ Manage third-party contributions
 
 Many aspects of managing incoming open-source contributions (core code, documentation, sample data, third-party deployment scripts, bug reports, etc) do not require deep technical expertise in the software.  Vendor proposes to handle, as an ongoing process, the parts of contribution management than can be separated from in-depth code review and technical decision-making.  State and Vendor would of course still make final decisions about what contributions to accept, and how, but Vendor would take care of the entry-level open-source project management bureaucracy as much as possible, including but not necessarily limited to:
 
- - Day-to-day communications with participants in the project's open-source forums;
- - First-pass review of contributions, to ensure proper formatting, description (log message), etc;
-  - First-pass review of public bug reports, to have initial dialogue with the reporter, resolve duplicates, make sure proper reproduction recipes are included, answer common questions, spot trends in the user community, etc.
- - Monitoring of the public discussion forums, to make sure the right parties are talking to each other, to help gather a formal knowledge base (e.g., FAQ) about the software, and to flag important items for State and/or Vendor's attention
- - Management of Contributor License Agreements, to make sure the project can legally and safely accept the contribution;
- - Management of contributors in GitHub;
+- Day-to-day communications with participants in the project's open-source forums;
+- First-pass review of contributions, to ensure proper formatting, description (log message), etc;
+- First-pass review of public bug reports, to have initial dialogue with the reporter, resolve duplicates, make sure proper reproduction recipes are included, answer common questions, spot trends in the user community, etc.
+- Monitoring of the public discussion forums, to make sure the right parties are talking to each other, to help gather a formal knowledge base (e.g., FAQ) about the software, and to flag important items for State and/or Vendor's attention
+- Management of Contributor License Agreements, to make sure the project can legally and safely accept the contribution;
+- Management of contributors in GitHub;
 - Management of public-facing documentation, to the extent that deep technical knowledge of Software is not required (which we anticipate being a fairly broad extent);
- - Coordinate with Vendor on contributions that are being accepted into the core code for general release, to make sure that the internal development process is plugged into the public forums in ways the community can use.
+- Coordinate with Vendor on contributions that are being accepted into the core code for general release, to make sure that the internal development process is plugged into the public forums in ways the community can use.
 
 We believe that this semi-separable part of contribution management is probably more than half of the typical public engagement overhead of running an open-source project – speaking roughly, somewhere between 70% and 75% of that overhead.  Having Vendor handle this portion would allow Vendor to concentrate on technical review and on just the communications that directly involve core code or State-desired features, and maximize the project's ability to get the full advantage of public engagement, which, if done right, far outweighs the overhead.  Vendor would of course remain free to become as involved with public technical engagement as they wish to be & have the bandwidth to be, and Vendor would fully support them in this.
 
@@ -489,6 +489,7 @@ shall cooperate fully with Customer in all reasonable and lawful efforts to
 prevent, mitigate or rectify such Data Breach. In addition to the notice requirement 
 contained herein, [Cloud Provider] will also immediately report any such Data 
 Breach to Customer's Legal Department at [insert telephone number or address]
+
 ___________________________________________
 
 **Insurance Clause for Cyber‐liability Insurance**.

docs/introduction.md

@@ -20,20 +20,21 @@ The toolkit takes a topic-focused approach, presenting practical
 recommendations around guidelines, tools, and frameworks to
 help agencies create a successful DPG.  It does not cover software engineering 
 best practices or tips on specific technology choices, but rather focuses on 
-higher level 
-topics, including: 
-* Understanding the types
-and value of open-source communities and project lifecycles
-* National
-and agency-level policies that relate to Free and Open Source Software
-(FOSS), including intellectual property and FOSS licenses, data
-privacy, and security
-* How to plan for and build organizational
-readiness to capture the full value of your open-source DPG
-* Tips for improving
-procurement, including sample contract language
-* How to analyze an
-existing FOSS product for adoptability  
+higher level topics, including: 
+
+* Understanding the types and value of open-source communities and
+  project lifecycles
+
+* National and agency-level policies that relate to Free and Open
+  Source Software (FOSS), including intellectual property and FOSS
+  licenses, data privacy, and security
+
+* How to plan for and build organizational readiness to capture the
+  full value of your open-source DPG
+
+* Tips for improving procurement, including sample contract language
+
+* How to analyze an existing FOSS product for adoptability
 
 The toolkit can be read as a whole or by
 individual module and topic. Key recommendations are
@@ -244,7 +245,7 @@ on:
    freely shared and are trained on open data sets and
    based on algorithms implemented in open-source software.
 
-   ## DPGs Are About Collaboration, Not Licenses
+## DPGs Are About Collaboration, Not Licenses
 
 Any discussion of "open" technologies and DPGs will eventually include
 mention of licensing.  It is in many ways foundational.  It is also