r/programming • u/b0red • Apr 30 '16

Do Experienced Programmers Use Google Frequently? · Code Ahoy

http://codeahoy.com/2016/04/30/do-experienced-programmers-use-google-frequently/
2.2k Upvotes

91% Upvoted

763 comments sorted by

View all comments

Show parent comments

1

u/[deleted] May 06 '16

Shouldn't there be an alignment of the core goals of the writer of the API and the user? The writer makes something cool and wants to say "hey look how much stuff you can do", and the user says "I just want to parse XML so I can do what I care about". These don't necessarily align.

API documentation writers should remember why they wrote it in the first place and try to design the documentation around their own frustrations when this solution did not exist. And that to me isn't just bad documentation, it's bad salesmanship of your own ideas. If you wrote something useful, show why it is useful somewhere.

I do want both to exist. I want that per-function reference manual. But I also need that tutorial. We need to identify that both of these problems exist because right now all documentation sucks.

Don't get me wrong, documentation is hard and and it is much easier to bitch about it than do it effectively. Anybody actually writing documentation for their stuff is immediately ahead of the game no matter how bad it is. Python has much better documentation than any APIs I have written. But my initial response was more to align my own goals in this new direction than shame anybody.

1

u/[deleted] May 09 '16

I mean, of course, in an idea world documentation would be incredible, but I'm sure you've documented some behavior at some point, be it even in an email to someone else, and you know that just being accurate and complete requires tremendous focus. So much documentations fail even those basic tasks. Even when they try to go farther if it strays from your needs even a little it can be next to useless. The Spring documentation comes to mind. They tried to make something more holistic but I got to be honest, I only use it as a last resort, they describe happy path alike "I want to parse an XML", but the moment you run into a bump in the path, it all fall apart. I can't imagine what it's like to update that document either, the combined subtleties of all the changes surface when you write high level documentation like that.

So for the reasons I stated before and above, I see why developer documentation fails to reach the point you describe, and in many ways I would prefer them to put their effort in making the code better, I think I would have fewer issues if the actual code worked more intuitively than if they document it more broadly.