> 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.
I just had an idea, but more in relation to documenting source code: what if there was a tool sort of like gofmt in that it has to be run in order for code to successfully compile, but instead of formatting, it actually checks if some or all of the variable names in functions or objects appear in some corresponding comment (like Python docstrings [0] or javadoc comments [1]).
I just came up with the idea and the first (bad?) heuristic now, and I didn't check to see if tools with these characteristics already exist. It would be bad initially [2] and it would be onerous for sure, but it would be a start.
Suppose this is the function we want to document (using examples modified documentation tests:
fn foo {
let x = 5;
let y = 6;
println!("{}", x + y);
}
Suppose we have a documentation requirement/heuristic of requiring the comment to have all the variables that are declared in the body of any given function. Then a comment like this would pass because whatever compilation step /processor sees that `x` and `y` both appear in the comment.
// Prints x + y
This would fail because `x` is not found:
// Prints z + y
This would pass but is not useful/misleading/wrong.
// y - x FTW!!!
This example is trivial and only uses the one simple heuristic such that it is both onerous and useless, but it would force the writer of the code to also write comments in accordance with said heuristic. In this particular case, if someone modifies the variable name, adds a new variable, or removes and existing once, then the compiler would force that individual to make a necessary change to that particular comment such that the comment cannot become stale (but the heuristic is bad, so it could still be useless :) ).
In the Python world, about the best you can do is enforce the existence of API documentation. Most Python linters can check that every module/class/function/method has a docstring, though of course they can't enforce that it's up-to-date or useful to a human.
Enforcing useful up-to-date documentation requires cultural setup work rather than technological setup work.
What about documentation, even "how-to use this product" documentation, that's generated from the code's comments directly?
So say you have a function that essentially implements the "--file" flag: what if the developer put a comment above this function explaining the function's purpose but also the documentation for the admin's use case, which would be setting up the solution?
I believe that if such documentation existed it would be a lot easier to update it when the code is changed (provided the API changes) and have it propogate through to the docs. The comments could also be three tiered: API docs, admin docs, user docs; each would explain to the relevant user how-to make use of the code at that point.
Obviously you could omit user/admin comments for functions that aren't "public facing", such as internal helper functions. But anything that's directly interacted via a CLI flag or HTTPS endpoint could have the documentation right there by the code handling that interaction... or not if it's not relevant.
This. 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?
Linux 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.
The worst thing is that I could actually use something like this, but that 1500 line stream of consciousness README makes me seriously consider how much time I want to put into it.
This 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.
It 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.
Check the “Perl jam” series of talks given at CCC. They are quite inflammatory, but the author does have a few good points. Specifically, he shows that one of the examples in the documentation for the CGI.pm module had an exploitable vulnerability.
Specifically, he shows that one of the examples in the documentation for the CGI.pm module had an exploitable vulnerability.
I think that's overstating things. He reported a "vulnerability" in Bugzilla which wasn't a security problem in Bugzilla because Bugzilla uses taint, which didn't do any database injection like he claimed, and which is unrelated to CGI.pm becaues Bugzilla doesn't use CGI.pm:
Furthermore, the examples in his presentation don't actually work, he relies on ignorance of lists and Perl data structures, and the one potentially interesting point he makes about calling functions in list context in hash initializers has been documented well understood as a potential mishap in web applications since 2000:
His presentation may have some value to someone spending their first week with Perl in a web context, but that person would have to wade through a lot of nonsense to get at that value.
>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]...
[3]: I recently downloaded a dwm statusbar manager called "dstat" (from https://www.umaxx.net/) and it's README was a really nice surprise: https://sub.god.jp/f/JmiFHE9S.txt (extracted and uploaded, since there's no public version)
As 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 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]
While the badges can get to be overkill (like in uBlock's case), I think having a small number with useful information (dependency status, code coverage, etc.) is helpful when quickly assesing a project.
Shame that the history of the maturity model looks like this:
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.
A 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.
I really like the "module: thing that changed" format for the title. We've been using that where I work. It helps keep commits focused and makes it much easier to read the log.
This maturity measure seems related to blog post driven development, as outside-in development. Are there any other related principles, approaches, and measures?
I'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.
It 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!
If 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.
Don'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.
Please 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.
I 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.
Documents 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.
It'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.
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.
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.
If 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.
I 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
One 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.
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.