4 ms·
> Github documentation is a disaster. They leave out critical parts. They don't provide examples. Everything they write is terse, confusing, and incomplete. Ag
by stevehawk 7y ago
> Github documentation is a disaster. They leave out critical parts. They don't provide examples. Everything they write is terse, confusing, and incomplete.
Agreed. A lot of times they seemed to use the ole "make a blog post about X and we'll call it documentation" strategy that a lot of others seem to be employing as well. The net result is useless documentation that is often outdated by the time a product is live. However, that doesn't change the fact that it's still the top search engine result for the topic or the de facto page many link to within their own actual 'documentation'.
- TheFiend7 7y agoWhile I do agree with you, I've found often times a good ol blog post with an example connecting some dots can be very productive. But I do agree with you that it's very from from being an alternative, and instead should be used to supplement healthy documentation.
- stevehawk 7y agoI agree with that. I know I have also grown particularly jaded because I've read so many useless blogs as everyone is trying to push out their own Medium articles so they can get that hot new FAANG job.
- hinkley 7y agoThere’s a really stupid simple partial fix for this but it seems to be non obvious to a lot of people. And that’s to watch a coworker who hasn’t used it before try to follow your docs. Try again, and then pick another coworker. By then it should be good enough for the majority to follow, and you take the rest of the questions as they come. Put the first draft out and you’ll be swamped with complaints.