4 ms·
> User testimonials and evidence of past performance in real development situations Please, not in a README. My problem with documentation remains: It's alway
by 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.
- tareqak 9y agoI 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. [0] https://www.python.org/dev/peps/pep-0257/ https://www.python.org/dev/peps/pep-0257/ [1] http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html http://www.oracle.com/technetwork/java/javase/documentation/... [2] https://en.wikipedia.org/wiki/Colorless_green_ideas_sleep_furiously https://en.wikipedia.org/wiki/Colorless_green_ideas_sleep_fu...
- steveklabnik 9y agoIn rustdoc, documentation examples are compiled and run whenever you run your tests. It's very helpful for this kind of thing. https://doc.rust-lang.org/stable/rustdoc/documentation-tests.html https://doc.rust-lang.org/stable/rustdoc/documentation-tests...
- vog 9y agoNice! Python has doctests which serve a similar purpose: https://docs.python.org/3.6/library/doctest.html https://docs.python.org/3.6/library/doctest.html
- slimsag 9y agoJust wanted to chime in and say that as a Go developer of almost 5 years now, running into Rusts' compiled examples has been quite cool. The cool thing about these is that you can actually (depending on the situation) make your examples your tests.
- slrz 9y agoWhat makes them so different from godoc's examples?
- movedx 9y agoWhat 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. See "godoc" as an example of this: https://blog.golang.org/godoc-documenting-go-code https://blog.golang.org/godoc-documenting-go-code The code truly does become the documentation at this point, and acts as a central point of truth.