3 ms·
25% of the total is documentation related .. Thats really interesting ... A 'smartly designed' documentation website can cater to 25% of total development queri
by nautical 11y ago
25% of the total is documentation related .. Thats really interesting ... A 'smartly designed' documentation website can cater to 25% of total development queries ?
- noir_lord 11y agoGood documentation can do more than that I think, take http://knockoutjs.com/ http://knockoutjs.com/ there documentation is incredible, I went from not been able to use it at all to using it comfortably in a week or two and most of the questions I've had since have been answered by the docs. It's pretty much the standard I'll aim in my own documentation in the future, lean, precise and covers the main cases with useful examples.
- xyzzyz 11y agoThe issue I think is that the documentation which is separated from code can easily go out of sync with the actual code, so it's worth to make writing documentation alongside the code as easy as possible, while trying not to obscure the code itself too much.
- acveilleux 11y agoI'd argue that for public APIs (defined as API users don't site next to/are the same as the API devs) this concern with "getting out of date" is moot compared to the benefit of detailed docs. If anything, it's the API signatures that get out of sync with the user's needs. And as anyone who's ever tried to deprecate public APIs will know, it's a real pain, frustrating to users and devs alike.
- shawn-butler 11y agoWhenever I see this comment I can't resist urge to make reference to Knuth: https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming No language developer ever seems to take it seriously as a design challenge to solve though. You get tools like rustdoc as "good enough"