9 ms·
A README maturity model
- irmc 9y agohttps://goo.gl/u1qWQ9 https://goo.gl/u1qWQ9 go visit this site as it's so useful
- sondr3 9y agoI feel like GitHub is partially being overrun by cheap and easy repositories to farm for stars, why would you ever need a README maturity model?
- WorldMaker 9y agoIf this repository additionally had badges that you could embed at the top of your GitHub README, I would expect it to be satire. I'm still not entirely convinced it isn't satire.
- simias 9y agoI'm curious, what does star farming get you? Is it just like farming karma on HN or is there a more practical reason to do that? Also, while I'm sure there's a gigantic amount of rather useless repos on github (I contributed my share...) doesn't mean that it's not a good idea to have guidelines to write usefull READMEs for projects that do matter.
- dredmorbius 9y agoTrust / credibility / reputation attacks, of various sorts.
- kyoob 9y agoIt looks like the main purpose of this repo is for open source project developers to open issues to get someone to help edit their projects' readme's. That's kinda nice!
- kevmo 9y agoDocumentation is part of the craft, so I appreciate casual attempts at formalizing conversation about commonly used methods of creating it.
- falcolas 9y ago> User testimonials and evidence of past performance in real development situations Please, not in a README. My problem with documentation remains: It's always out of date, and frequently contradictory. I'm trying to work with Kubernetes right now, and by this "maturity model", it's a Level 5. That doesn't actually provide any real help though, since k8s is moving so quickly the tremendous volumes of documentation which make it so attractive to managers and leaders just can't keep up. What arguments should I be providing to kubelet? Depends on whether you're reading the code, the admin guide, or the getting started from scratch guide. None of which, by the way, reference the version of k8s you're going back to. The API docs generated from the code are a bit better, but they were written as part of the code, and the descriptions are incomplete and confusing without the context of the code (separate rant - that codebase is split between so many repos you'll go slightly mad trying to learn what is where if you're not already familiar with it). In the end, we always end up going back to the code; even k8s documentation acknowledges this by constantly linking back to GitHub.
- abhishekpathak 9y agoThis. There's an almost inevitable orchestration involved in maintaining good documentation for a fast-moving codebase. Tools like Swagger[1] are good for automatically generating API documentation, but beyond that there is little help for maintaining generic README-style documentation. How do large, fast moving projects like the linux kernel manage this? [1]: https://swagger.io/ https://swagger.io/
- mjw1007 9y agoLinux delegated its user-facing documentation to third parties pretty much from the beginning. Even for those things which have documentation in Documentation/, there is no formal or informal rule that if you make a change which causes existing statements to become false you have to update them.
- Sujan 9y agoWhich doesn't reduce the usefulness of the linked document at all. If your project is bigger, README probably should not be a full documentation of the project but link to the actual documentation.
- Sujan 9y agoNice project. Shame that the history of the maturity model looks like this: https://github.com/LappleApple/feedmereadmes/commits/master/README-maturity-model.md https://github.com/LappleApple/feedmereadmes/commits/master/... Even when editing in the web UI you can - and should - set a commit message so one can actually understand how a document evolved without going through the diffs.
- busterarm 9y agoNext Up: Git Commit Maturity Model
- deleted 9y ago[deleted]
- blattimwind 9y agoA level five commit is product-oriented, contains a vision statement for the change, has its own slogan and is updated at weekly or even daily intervals, so inaccuracies are unlikely.
- busterarm 9y agoYou surpassed my level of snark and reached limits I considered unachievable. Well done!
- jph 9y agoHow to write a great git commit message: http://github.com/joelparkerhenderson/git_commit_message http://github.com/joelparkerhenderson/git_commit_message
- scrollaway 9y agoThe Wine project has been my go-to reference for what commits should look like in a large and complex project: https://github.com/wine-mirror/wine/commits/master https://github.com/wine-mirror/wine/commits/master During the short time I contributed to Wine, I really got to appreciate their high quality source control discipline.
- Sujan 9y ago> A line about the average response time to issues and/or pull requests. Does someone know any projects that have this?
- tehno 9y agoThere should be a README-embeddable badge service for this. Anyone up for writing one?
- hobofan 9y agoI know that there is an embeddable image of issues/PRs closed/opened over the last weeks, that is used in some READMEs, but I can't remember any of the repos right now.
- reificator 9y agoI'd start with a scan of https://shields.io/ https://shields.io/
- jehna1 9y agoHere's a bootstrap template for creating your own README.md: https://github.com/jehna/readme-best-practices https://github.com/jehna/readme-best-practices You can use it to quickly go through most common information you should include in your own readme.
- carussell 9y agoIt's a bad idea to use first-person voice in READMEs on GitHub. It breaks down when people give in to GitHub's insistence on forking. If you want to include a first-person account (motivation, etc), put it in a blog post and link to it from the README—then everyone will be able to tell who "I" refers to.
- Sujan 9y agoI like how the project name is formatted as code. It's missing a TOC though, scrolling through it doesn't give an overview what it contains.
- voltagex_ 9y agoIs there an easy way to generate a TOC from an existing Markdown file?
- Sujan 9y agoDepends on where you are rendering the Markdown. In Jekyll with kramdown you can use {.toc} to get an automatically generated table of contents. On Github this doesn't exist, so you have to use an external tool like https://ecotrust-canada.github.io/markdown-toc/ https://ecotrust-canada.github.io/markdown-toc/ (Google "markdown generate TOC" for alternatives)
- jehna1 9y agoDocuments like README have a tendency of getting out of date really quickly — especially if you add dependencies between different content inside the file. I think anyone using Confluence (or similar wiki-style space) can agree. Including table of contents in your README is pretty big overhead if you cannot generate it automatically. This template is meant to be a good starting point for any size of project, so it was a conscious decision to leave table of contents out of it.
- mitchtbaum 9y agoThis maturity measure seems related to blog post driven development, as outside-in development. Are there any other related principles, approaches, and measures? https://en.wikipedia.org/wiki/Outside%E2%80%93in_software_development https://en.wikipedia.org/wiki/Outside%E2%80%93in_software_de... http://blog.estimote.com/post/119525082855/user-stories-on-steroids-how-estimote-uses-blog http://blog.estimote.com/post/119525082855/user-stories-on-s... https://news.ycombinator.com/item?id=958480 https://news.ycombinator.com/item?id=958480
- nerdponx 9y agoGithub-Star-Driven development?
- abainbridge 9y agoThis reminds me of the worst readme I ever read: http://dpdk.org/browse/apps/pktgen-dpdk/tree/README.md http://dpdk.org/browse/apps/pktgen-dpdk/tree/README.md It's extremely long and almost impossible to read. It starts off as it means to go on: Pktgen is a traffic generator powered by Intel's DPDK at wire rate traffic with 64 byte frames. For that to work as a sentence, it needs the phrase "capable of generating packets" putting in the middle. A bit lower down it spends 200 lines showing what happens if you type "ls" in various folders on the developer's machine. Helpful. It's fascinating to try to read because it's so mad. If you are the author, I'm happy to provide some more constructive feedback...
- teddyh 9y agoThe rules for traditional README files are documented here: http://en.tldp.org/HOWTO/Software-Release-Practice-HOWTO/distpractice.html#readme http://en.tldp.org/HOWTO/Software-Release-Practice-HOWTO/dis... https://www.gnu.org/prep/standards/standards.html#index-README-file https://www.gnu.org/prep/standards/standards.html#index-READ...
- tedunangst 9y agoTheir own README is at most only level two. No badges.
- rvshchwl 9y agoDon't completely agree with the guidelines presented in the maturity model, but I do think that a well written README goes a long way in making your project discoverable, identifiable or even presentable. I have had old projects for which I am now really glad that I took the time to write good READMEs when I did, because I can refer back to them and still know what I am reading through. It's a good practice, like commenting your code.
- bpicolo 9y agohttps://github.com/mcohen01/amazonica https://github.com/mcohen01/amazonica is the best README I've seen. Relevant examples for every piece of the library, and some nice-to-have performance graphs. The 95%-use-case getting started is really the best thing you can do in a README in my opinion, and amazonica totally nails it.
- Sujan 9y agoI like how the project name is formatted as code. It's missing a TOC though, scrolling through it doesn't give an overview what it contains.
- bpicolo 9y agoThe "Supported Services" is the table of contents
- Sujan 9y agoIf this is the intention, then it is a really terrible one. First link sends me 1/3 down the page. This actually only links to the examples, the 10 other (documentation) sections/headlines are missing.
- bpicolo 9y agoYeah, that could maybe be tweaked a bit. The examples are really where this one shines for me. :) I didn't feel more ToC was overly necessary.
- athenot 9y agoThis is one area that Perl's CPAN really got right. Pick just about any random module, and you're immediately greeted with a short synopsis showing the use-case. When you search for something and find 5 matching modules, you can quickly evaluate them on the basis of how easy they are to use relative to your codebase. Random obscure module: http://search.cpan.org/~prasad/X12-0.80/lib/X12/Parser.pm http://search.cpan.org/~prasad/X12-0.80/lib/X12/Parser.pm OK so in the first paragraph, I know how to parse an X12 transaction file and get the results into my code. This boils down to know your audience.
- pwenzel 9y agoI think this is a great example. I don't even know what an X12 transaction file is, but boy howdy, I know how to parse it now!
- avian 9y agoIt is a double-edged sword though. It makes it easier for people to use a module without understanding it fully (or at all). The CGI.pm fiasco is one example, where people were copy-pasting the one-liner in the synopsis and opened themselves to an attack. A lot of things are complicated and can’t be usefully summarized in a few lines.
- plttn 9y agoI wasn't around for this fiasco, what exactly was it?
- perlgeek 9y agoPlease also include a line about the license in your README. The full license can go into a separate file, but a paragraph like "This project licensed under the GPL v2 license. See the LICENSE file for details" can be extremely helpful, and is missing far too often.
- dguo 9y agoI like this idea of a maturity model. It makes sense that READMEs grow in scope with their projects and can be evaluated accordingly. To add to the README discussion, I made a small website a few months ago for README guidelines, though it's more geared towards beginners: https://www.makeareadme.com https://www.makeareadme.com
- daptaq 9y ago>Embedded visual aids like diagrams and demos. >The build status identifies specific project aspects that are incomplete and/or causing instability. >One or more badges showing code coverage or other quality metrics. I really have to disagree with points like these. I always hate cloning a project and then opening the README to find a totally unreadable mess of Markdown links and images or worse still - literal HTML. As an example, look at uBlock's README.md[0], which even though uBlock is a fantastic project in it's own right, has a horribly unreadable README. If you're already adding a README file within your code repositoy, you should assume that people will read it locally, without fancy HTML rendering. The whole point behind markup was to have a syntax which could be easily parsed by computers and humans alike (it was inspired by the plaintext email formatting style after all!). Graphics and badges should be put on a website, in this case for example GitHub's github.io service. Specifics should be placed in a man page or something comparable. Links should either be autolinks[1] or reference links[2], to keep the document clean and structured. I'm sure others could come up with more and better recommendations on how to use "normal" markdown to still create a decent README's for GitHub. Maybe we don't even need Markdown and we can just use plain utf-8[3]... [0]: https://raw.githubusercontent.com/gorhill/uBlock/master/README.md https://raw.githubusercontent.com/gorhill/uBlock/master/READ... [1]: http://spec.commonmark.org/0.28/#example-565 http://spec.commonmark.org/0.28/#example-565 [2]: http://spec.commonmark.org/0.28/#reference-link http://spec.commonmark.org/0.28/#reference-link [3]: I recently downloaded a dwm statusbar manager called "dstat" (from https://www.umaxx.net/ https://www.umaxx.net/) and it's README was a really nice surprise: https://sub.god.jp/f/JmiFHE9S.txt https://sub.god.jp/f/JmiFHE9S.txt (extracted and uploaded, since there's no public version)
- Cyphase 9y agoAs a complete aside, some people (in an IRC channel) and I just spent 20+ minutes trying to figure out why https://sub.god.jp/f/JmiFHE9S.txt https://sub.god.jp/f/JmiFHE9S.txt was displaying in a non-default font in Firefox. Turns out it was being treated as encoded as Shift JIS, because the encoding wasn't explicitly specified in the headers and the TLD is .jp .[1] [1] https://dxr.mozilla.org/mozilla-central/source/dom/encoding/domainsfallbacks.properties#72 https://dxr.mozilla.org/mozilla-central/source/dom/encoding/...
- 9y ago
- mbrookes 9y agoI believe it's a mistake to try and cram everything into the README. We've gone the opposite direction with Material-UI. Compare 0.x (before): https://github.com/callemall/material-ui/blob/master/README.md https://github.com/callemall/material-ui/blob/master/README.... With v1-beta (after): 1.0-beta: https://github.com/callemall/material-ui/blob/v1-beta/README.md https://github.com/callemall/material-ui/blob/v1-beta/README...
- callesgg 9y agoLevel 4 actually seams best to me.
- DonbunEf7 9y agoThese levels are known to SREs as Initial, Repeatable, Defined, Managed, and Optimizing: https://en.wikipedia.org/wiki/Capability_Maturity_Model#Levels https://en.wikipedia.org/wiki/Capability_Maturity_Model#Leve... These levels are known to Discordians as Chaos, Discord, Confusion, Bureaucracy, and The Aftermath: https://en.wikipedia.org/wiki/Principia_Discordia https://en.wikipedia.org/wiki/Principia_Discordia
- _kst_ 9y agoOne simple requirement is that a README file should include, near the top, a brief summary of what the project is. I've seen too many README files that leave that out. Knowing what changed in the latest point release doesn't help me if I don't know what the whole thing is for.
- crehn 9y agoAlso applies to landing pages. Just explain briefly what the project is about.
- billmalarky 9y agoSpeaking of, I wouldn't mind getting some feedback on my latest README. https://github.com/billmalarky/react-native-image-cache-hoc/blob/master/README.md https://github.com/billmalarky/react-native-image-cache-hoc/... It's pretty much the first time I've put effort into trying to make a README before since I'm now trying to make good documentation a serious development habit. I'm still adding coveralls but I'd be interested to hear anyone's feedback.