README prescription: include other practical information
fulldecent opened this issue · 4 comments
This document prescribes information that MUST be in the README.
Some other information SHOULD be in a README:
- What valuable contributions would you welcome from the community? (Don't be shy! You will be surprised by the service you get from the public if you ask politely.)
- Discussion: this should be a major motivation for project managers to release projects
- What organization is publishing the project and who is your point of contact for accepting contributions to the project?
- How does this project help your organization's mission and the public?
- Discussion: this is a sneaky way of setting project scope, since nobody likes to clearly define project scope.
@fulldecent Your first point is a REALLY GOOD idea; do you want to take a stab at it and send me a pull request against the develop branch?
For the second point, one of the issues that I need to fix is getting ARL's policy in line with the code.gov metadata schema. That will include all the information you suggest, along with quite a bit extra. Their schema has been moving pretty quickly, which is the only reason I haven't, but you reminded me that I need to log an issue or I'll forget.
The last point is where the Form 1 process is supposed to help. To get anything out the door, ARL employees are supposed to convince the ARL leadership that the project is worthwhile to release, and they have to convince security that it can be released. That naturally implies a 'whole truth and nothing but the truth' kind of mentality where the project's scope has to be complete and clearly defined. At least, that's what I hope! If it isn't clearly defined, would you take a stab at clarifying it? Again, it will need to be a pull request against the develop branch (or make up your own; whatever works for you!)
Thank you, I have implemented the first item in PR #8.
Per your explanation, point of contact metadata is addressed in code.json. So my second point is moot.
Project scope is captured in Form 1, but I do not see how that information gets back to the public. I've seen too many projects go haywire because scope is in one person's head but not written on paper.
The project scope has to be written down as part of the ARL process. That is what the security team uses to determine if the project has gone out of scope. The developers are encouraged to copy that to their README.md (or vice versa), so it should always state what the project is doing, and where it is going. Note that Major Reviews can happen quite often, and must occur at least once a year, so there is a forcing function to ensure that a project stays within scope.
#8 is merged and other points are addressed. Thank you, closing.