I've said before that the killer feature that launched Java wasn't garbage collection or checked exceptions, but javadoc. Autogenerating HTML documentation based on strictly-typed interfaces was absolute genius and I really haven't seen it topped by any modern language.
The problem with this family of tooling is that they are essentially fill-the-blanks forms and that all the surrounding ceremony is generated indiscriminately of wether the blanks were actually filled or not. Or worse: (pre-)filled with redundant placeholders like "@return returns the $Typename". The frustration pointed out by OP is that when you see a page of "blank" generated documentation you never know if there i…
Exatly. A "/ @return String */" is absolute garbage Javadoc, but that does not mean that the concept is bad or cannot be put to good use.
Same here. Why is documentation standard so low? Tell me how that buffer management works (do I provide it? delete it? when? how?); how threading is supported (reentrant? send/receive at the same time/different threads? interprocess?); dependencies (necessary initialization? teardown? states in between?); efficiency (can I hold a lock around the call? does it block?). Instead, we often get nothing but a method name a…
> Why is documentation standard so low? Even in companies where good documentation would raise revenue in a way that the sales team notices[1], someone still needs to write it and someone still needs to make the business case for writing it. Engineers could, but many don't. If you're passionate about good documentation, but don't think you can deliver, it would be foolish to unless someone else is doing the writing.…
One book that (unexpectedly) gave me good tips on 'how to write' was Zen and the art of motorcycle maintenance. At some point the main character, who's a teacher in rhetoric, finds out that no one of his students know how to write. They all learned through analysis how great author have written this or that way, but they don't know where to start. They don't know the great authors probably didn't consciously decide to say 'here I'll put a metaphor, now a simile, and here you go, ellipsis'... They probably started with something simple, badly expressed, and refined, polished, restarted, embellished, simplified... The bigger hurdle of his students seems to be 'the first draft', the initial idea, the first words. Not even a 'blank page' problem. He gives them exercises in pure description, simpler and simpler and most of his students can't even start the first words.
The funny 'solution' is just to start and write... Something... (and I'm not doing the book justice here sorry... I really like it, not as a philosophy reference (I've read many negative critics on this), but how it mixes the pain of being a father or a kid, the pain of mental illness, the pain of feeling cleverer than your peers, and the pain of being a teacher, a writer and a friend. All wrapped in a beautiful and sad storyline, lots of beautiful American scenery, and some advice on motorcycle maintenance...).
What I’m always looking for with technical documentation - which I rarely if ever am able to find - is, what problem is this thing is trying to solve? How is, say, Angular better than plain-old Javascript? How is Spark better than a shell script triggered by a cron job? How is Spring better than Java by itself? What sorts of problems are they most appropriate for? Sometimes I suspect that I can’t find this informatio…
I'd generalize this with a "why". Why does this project exist? Why does that functionality exist? Why does it uses those types? etc
(though you could say that this is part of the "Explanation" quadrant)
I use lack of ambiguity as a measure of documentation quality. The best (honestly the only good) documentation that I've ever found is at: " rel="nofollow">https://www.php.net/ For example: https://www.php.net/echo Note how even this simple arbitrary example tells us "No additional newline is appended." It's shocking to me how many other guides would leave something that critical out of the manual. Then there are eve…
I have to agree. Php is probably the easiest and moat productive languages I ever learned. The docs were great and the error messages always pointed me im the right direction very quickly. It's no surprise that the language caught on as it did. Ruby, by contrast seemed so hard to learn and I could never see what the advantage was over php so I never had the motivation to push past the difficulties of learning it.
I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. This does of course require human-readable description in all the endpoints. But that's the same as only an autogenerated function signature in code documentation vs an added human-readable description.
I've said before that the killer feature that launched Java wasn't garbage collection or checked exceptions, but javadoc. Autogenerating HTML documentation based on strictly-typed interfaces was absolute genius and I really haven't seen it topped by any modern language.
The .NET standard library docs are a thing of beauty because they intermingle autogenerated javadoc-style documentation with generally well-written freeform "remarks" sections that include more general explanations, context, and code samples.
I use lack of ambiguity as a measure of documentation quality. The best (honestly the only good) documentation that I've ever found is at: " rel="nofollow">https://www.php.net/ For example: https://www.php.net/echo Note how even this simple arbitrary example tells us "No additional newline is appended." It's shocking to me how many other guides would leave something that critical out of the manual. Then there are eve…
Also a major overlooked factor in PHP's documentation success is having a specific URL for each function. Some documentation sites use #anchors to jump to spots in a document (ex: boostrap), but it's not good enough. What ends up happening is people search Google for something granular like "mysql concat" and end up on tutorial sites like w3schools. Why? Because the MySQL documentation throws CONCAT() into a giant messy page called "String Functions and Operators": https://dev.mysql.com/doc/refman/8.0/en/string-functions.htm...
Google "mysql concat" and see for yourself. Giant one-page docs are terrible. PHP got it right from the beginning.
I've said before that the killer feature that launched Java wasn't garbage collection or checked exceptions, but javadoc. Autogenerating HTML documentation based on strictly-typed interfaces was absolute genius and I really haven't seen it topped by any modern language.
This is also a great feature of Haskell, especially Hoogle, which is what I miss the most when working in Java. If I want to find a function which, say, removes items from a Map based on a function over values, in Java I have to look and see if it's in the Map class. Nope. Is it in Guava Maps? Ah, there it is, "filterValues". In Hoogle, I can type `Map k v -> (v -> Bool) -> Map k v` into the search bar, and it finds…
I'm impressed. Being able to search for functionality by the function signature seems incredibly useful. In the "Verb-Noun vs Noun-Verb" thread from a couple days ago [0], people were saying that OO languages make autocomplete much easier because you start with the parameter you're operating on. But, autocomplete (at least in IntelliJ) only lets you search by method name. There have been lots of times where I want to search by return type or param type instead.
When you're looking for functions, do you generally use Hoogle, or do you have a local autocomplete-like feature hooked in to your editor? I really want to be able to use this while writing code.
> Why is documentation standard so low? Even in companies where good documentation would raise revenue in a way that the sales team notices[1], someone still needs to write it and someone still needs to make the business case for writing it. Engineers could, but many don't. If you're passionate about good documentation, but don't think you can deliver, it would be foolish to unless someone else is doing the writing.…
I think free writing such as journaling can help one get better at writing first drafts. Its important to practice the skill of getting something written.
Yes, since my commute changed, I've been regularly freewriting on the train and it has been helpful.