October 29, 2017 5:47 pm
I’m writing this for my fellow DXCers, but I’d expect the points I make here likely apply to any open source project.
Because that’s the first thing that somebody visiting the project will see.
Is the README written for them – the newbies – the people who’ve never seen this stuff before?
Does it explain the purpose of the project (why)?
Does it explain what is needed to get the project and its dependencies installed?
Does it explain how to use the project to fulfil its intended purpose?
Does the writing flow, with proper grammar and correct spelling? Are the links to external resources correct? Are the links to other parts of the project correct (beware stuff carried over from previous repos where the project might have lived during earlier development)?
Is the Description field filled out (and correct, and sufficient to keep the lawyers happy)?
Is the project name in line with standards/conventions?
Have we correctly acknowledged the work of others (and their Trademarks etc.) where appropriate?
Is the LICENSE.md correct (dates, legal entities etc.)?
Is there a CONTRIBUTING.md telling people how they can become part of the community we’re trying to build around this thing (which is generally the whole point of open sourcing something)?
I might just do one to find out; but seriously – somebody needs to be on the hook to respond to PRs, and they need a combination of empowerment (to get things done) and discretion (to know what’s OK and what’s not).
I just found this Sample Readme, which seems like a starting point. Maybe I need to fork it to cover the items above (as it seems like it’s intended for an audience inside a company).
Posted by Chris Swan
Categories: DXC
Tags: documentation, open source, README.md
Mobile Site | Full Site
Get a free blog at WordPress.com Theme: WordPress Mobile Edition by Alex King.
Chris, This is one of the “DXC:ers” commenting (a DXC lawyer in fact). This made my day. For the record, much in your post is generally applicable to any type of random “approval request”. Keep it up!
By Petter on March 15, 2018 at 10:36 am