edits

readme_prompts.md

@@ -1,28 +1,24 @@
 # Instructions for creating a [README.md](http://README.md)
 
-Write a comprehensive README.md for the project.  First, review thse instrucitons. If unsure about anything in these instructions, ask, but try to use your judgment and inherent knowledge first. Then review the project in full, observing what is *actually present*.  
+Review these instructions. If unsure about anything in them, ask, but try to use your judgment and inherent knowledge first. Review the project in full, observing what is *actually present*. Write a comprehensive README.md for the project. 
 
 ---
 
 # The Inviolable Rule:
 
-In writing the README.md, do not make up information about the project.  
+Do not make up information about the project. Only write about code and other aspects of the project that are present and that can be observed by a human examining the repository.
-
-Only write about code and other aspects of the project that are present and that could be objectively observed by a human examining the repository.
 
 ---
 
 # Content - Above The Fold
 
-
-
 ### Do:
 
-Always use hierarchical headers (e.g. #, ##, ##) that demarcate and group content by topic or logical relation. 
+Use hierarchical headers (e.g. #, ##, ##) that demarcate and group content by topic or logical relation.
 
-This information should appear in the first ten to fifteen lines (as hard wrapped to no more than 80-100 cols) of the README.md.: A concise but complete description of the functionality and purpose of the software as the first line (e.g. make is a command line tool for running builds based on a rules-based Makefile).
+This should appear in the first ten to fifteen lines (as hard wrapped to no more than 80-100 cols) of the README.md.: A concise but complete description of the functionality and purpose of the software (e.g. make is a command line tool for running builds based on a rules-based Makefile).
 
-Hyperlink the first word (the name of the package) to the project's official website.  If one is not provided, assume it is the same repo page on which the README.md appears. This is because people might be cloning the repo and viewing the README.md in other contexts, or offline ( e.g. [make](https://www.gnu.org/software/make/) ).
+Hyperlink the first word (which should be the name of the package) to the project's official website.  If one is not provided, assume it is the same repo page on which the README.md appears, because people might be cloning the repo and viewing the README.md in other contexts, or offline ( e.g. [make](https://www.gnu.org/software/make/) ).
 
 Include the primary programming language name in the first sentence description. Any tightly-coupled libraries (like React, for example) should also be mentioned. (e.g. written in C or written in [ES6](https://262.ecma-international.org/6.0/) and [JSX](https://facebook.github.io/jsx/) using [React](https://react.dev/) ).
 
@@ -30,15 +26,15 @@ Include the license name in the first sentence description, and link to the lice
 
 Include the approximate date of original release, as well as the current version and release date (check the current date from a verifiable outside source).
 
-Make it clear who you envision the end user of the software to be: A command line helper app written by one person in a weekend that spits out fun emoji and a cloud-native API gateway proxy sidecar container that requires a working etcd cluster to start up are likely going to end up in daily use by very different types of users (or at least users using very different contexts).
+Make it clear who you envision the end user of the software to be: A command line helper app written by one person in a weekend that returns fun emoji versus a cloud-native API gateway proxy sidecar container that requires a working etcd cluster to start up are likely going to end up in daily use by very different types of users (or at least users in very different contexts).
 
 e.g. for use by developers of large, complex, multi-language projects
 e.g. for use by operators of large-scale Kubernetes clusters
 e.g. for use by security administrators in regulated financial environments
 
-Make extensive use of hyperlinks; err on the side of too many if you aren’t sure. Link everything that can be linked in the first section; company names, library names, programming language names, license types, distributions, OSes, dependencies, file formats, standards documents, etc. If there isn’t an “official” site for the entity, link a Wikipedia article. Make it very easy for people to get additional context if they want it (or to ignore it if they do not).
+Make liberal use of hyperlinks; err on the side of too many if you aren’t sure. Link everything that can be linked in the first section; company names, library names, programming language names, license types, distributions, OS, dependencies, file formats, standards documents, etc. If there isn’t an “official” site for an entity, link a Wikipedia article. Make it easy for people to get additional context.
 
-links in markdown are in brackets with the URL in trailing parentheses: [Go](https://golang.org)
+Links in markdown are always in brackets with the URL in trailing parentheses: [Go](https://golang.org)
 
 ---
 
@@ -52,63 +48,63 @@ Mention whatever versioning scheme is used, whether SemVer or yyyymmdd.xx or yy.
 
 Include usage/invocation examples (with corresponding output) if the project is small or simple.
 
-[The following should be provided and/or referenced by the human providing these instructions]: Include some text-based screenshots ( or  blocks or triple-backticks in markdown) if applicable. Avoid graphical screenshots if it is just text.]
+[The following should be provided and/or referenced by the human providing these instructions]: Include some text-based screenshots (or  blocks or triple-backticks in markdow) if applicable. Avoid graphical screenshots if it is just text.
 
-[This should also be provided, ask for this if it is not]: Include the reason the project came into existence  You do not need a whole brand story (unless you want to), just a sentence or two is fine.
+[This should also be provided, ask for it if it is not]: Include the reason the project came into existence  You do not need a whole brand story, just a sentence or two is fine.
 
-Include some information (with code examples) of any specialty programming language features or styles that the project focuses on, if any. For example, if you are a functional programming library, show some common functional programming usage examples before and after your library so people can understand why you exist.
+Include some information (with code examples) of any specialty programming language features or styles that the project focuses on.
 
-Do include a top level “Getting Started” section for first-time users. This should include a quickstart guide (possibly inline in the README, or a link to the appropriate subsection of documentation, a link to the full documentation, and a link to the community participation section.
+Include a top level “Getting Started” section for first-time users. This should include a quickstart guide (inline in the README, or a link to the appropriate subsection of documentation, a link to the full documentation, and a link to the community participation section.)
 
 ### Participation
 
-Include a top-level “Participation” section.
+Include a top-level “Participation” section, with  an explanation of the contribution process, if provided. It should:
 
-Include a top level “Authors” section that lists the names (or usernames) and email addresses of the maintainers or primary authors. Link to their personal pages/profiles if provided. Full names and websites are optional; email addresses are not. Try to make this reasonably complete, as it clarifies the size of the project management.
+State how bug reports will be accepted e.g. via email, or via Git issues (default, if not otherwise provided, should be Git issues). 
 
-Include an explanation of the contribution process, if provided, and how bug reports will be accepted e.g. via email, or via Git issues (default, if not otherwise provided, should be Git issues).  
+Default statement on pull requests: they will be accepted for review, but project authors make no guarantee that they will be merged.
 
-Default statement on pull requests should be that they will be accepted for review, but project authors make no guarantee that they will be merged.
+Include a list of contribution requirements, if any. Link to code style guidelines or linting configuration that must pass, if provided.
-
-Include a complete list of any contribution hard requirements. Link to code style guidelines or linting configuration that must pass, if provided.
 
 Be clear if a Contributor License Agreement (CLA) or other legal document is required to contribute.  Default, if no further instruction is provided, is that a CLA is not required.
 
+Include a top level “Authors” section that lists the names (or usernames) and email addresses of the maintainers or primary authors. Link to their personal pages/profiles if provided. Full names and websites are optional; email addresses are not. Try to make this reasonably complete, as it clarifies the size of the project management.
+
 ### Ideology
 
-State what sort of community participants can expect. If you have a Code of Conduct, link it and list it by name.  If you do not have one, mention that. Keep this transparent so people can make informed decisions about participation.
+If the project has  a Code of Conduct, link to it. If not, state that. Keep this transparent so people can make informed decisions about participation.
 
-Make it clear if the project exists primarily as a tool for a for-profit company, such as the so-called “open core” offering of a startup.
+Make it clear if the project exists primarily as a tool for a for-profit company, such as a so-called “open core” offering of a startup.
 
-Make it clear if the project is one free software component of a larger system that includes nonfree software, or vice versa.
+State if the project is one free software component of a larger system that includes nonfree software, or vice versa.
 
-Make it clear if the project/software exists to interface with a single centralized service, and link to that service and its EULA or TOS.
+State if the project/software exists to interface with a centralized service. Link to that service and its EULA or TOS.
 
-Make it clear if the software is going to transmit user activity data off of the device on which it is run. Link to the associated privacy policy, if so. Assume it will not do so, as surveillanceware is evil.
+Make it clear if the software will transmit activity data off the device where it runs. If it does, link to the privacy policy from the README.md.
 
 ### DO NOT:
 
-These "DO NOTS" apply to the entirety of the README.md (both above and below the fold).
+These "DO NOTS" apply to the entirety of the README.md (above and below the fold).
 
-Do not assume the "above the fold" README.md audience has ever heard of the authors or project.
+Do not assume the README.md audience has heard of the authors or project.
 
-Do not assume that the audience knows engineering/specialty jargon. Of course, technical language must be employed – this is a software project. But, the audience is the general web-using public. README.md language should endeavor to be accessible, not opaque. 
+Do not assume that the audience knows engineering/specialty jargon. Of course, technical language must be employed – this is a software project. But, the audience is the general web-using public. README.md language should endeavor to be accessible, not opaque.
 
-Do not use acronyms, initials, or abbreviations without using the complete text for the first use, with the acronyms following thereafter. 
+Do not use acronyms, initials, or abbreviations without using the complete text for the first use, with the acronyms following thereafter.
 
 e.g. Extract, Transform, Load (ETL)
 e.g. Application Program Interface (API)
 e.g. Software Development Kit (SDK)
 
-Do not worry about the README.md being too lengthy, as long as you always:
+Do not worry about the README.md being lengthy, as long as you:
 
 1. Write in concise language.
 2. Favor short, declarative sentences.
-3. Eliminate, wherever possible, adverbs "of frequency or degree" (generally words ending in -ly, for example, "quickly," "completely," "easily").
+3. Eliminate, where possible, adverbs of "frequency or degree" (generally words ending in -ly, for example, "quickly," "completely," "easily").
 4. Use logical section headings that demarcate content by subject.
 
-(If sections get too long, they can be factored out later to sub-files in a documentation directory at path /docs/ – and replaced with a link to those files. It is acceptable for the README.md to contain all of the primary documentation for a small project.)
+(It is acceptable for the README.md to contain all of the primary documentation for a small/medium project. If sections get long, they can be refactored later to sub-files in a documentation directory at path /docs/ – and replaced here with a link to those files.)
 
 Do not obfuscate email addresses; write them in full, make them links, clickable via mailto: URLs. Obfuscation is ineffective; spammers and web crawlers know how to use regex. The web is not the place to fight email spam.  That is for email and network infrastructure.
 
-DO NOT, ever, EVER use emojis of any kind.
+DO NOT, ever, EVER use emojis.