News for hackers. Stuff that matters.
Re:Contributing Without Code by barnacled on Wednesday December 30, 2020 @09:12AM (#25581819)
That's a very good habit to be in, however when it comes to external-facing stuff, e.g. APIs, or stuff that needs a lot more detail (and especially examples) then you're going to need more than self-documenting code.

Of course getting out of sync is a real massive issue and a total pain. But that's another reason for people to contribute to such things :)

Re:Contributing Without Code by opportune on Wednesday December 30, 2020 @12:37PM (#25583751)
For APIs, there are tools to parse out comments (that the linter requires) into the API description. Doesn't give examples or much of a "when to use this" usually, but I've found it's better than nothing.

For me personally, even though I dislike these auto-generated docs since they're quite terse (and tend to display niche parts of the API just as prominently as the parts you likely want to use), I tend to find them much more reliable than more detailed guides precisely because they tend not to desync, so I often don't even bother with well-written guides anymore, since they are much more likely to waste my time (or at least be inaccurate).

I'd expect many other developers have the same level of trust issues I do, to the point that those shitty auto-generated docs are in some ways better than really nice, detailed docs, because they are easier to trust. I'm unlikely to break the habit of ignoring detailed docs/guides unless it's coming from some big project where they're uniformly good. Otherwise, reading them tends to be a waste of time IMO.